prismcast 1.10.2 → 1.11.0

package/dist/native/proxy.js

@@ -5,11 +5,10 @@
 import { LOG, chromeFetch, realClock, startTimer } from "../utils/index.js";
 import { buildPrerollEntries, computePrerollWindow } from "../streaming/preroll.js";
 import { decryptSegment, deriveIvFromSequence, fetchDecryptionKey, parseExplicitIv } from "./decrypt.js";
-import { storeAudioSegment, storeSegment, updateAudioPlaylist, updatePlaylist, updateVideoPlaylist } from "../streaming/hlsSegments.js";
+import { findNamedInitSegment, pruneNamedInitSegments, storeAudioSegment, storeNamedInitSegment, storeSegment, updateAudioPlaylist, updatePlaylist, updateVideoPlaylist } from "../streaming/hlsSegments.js";
 import { CONFIG } from "../config/index.js";
 import { buildPlaylist } from "../streaming/playlistBuilder.js";
 import { getStream } from "../streaming/registry.js";
-import { removeManifestInterceptor } from "../browser/manifestInterceptor.js";
 import { resolveUrl } from "./probe.js";
 /* This module implements the native HLS proxy that replaces Chrome screen capture for viable streams. It polls the service's variant manifest at regular intervals,
  * detects new segments by tracking #EXT-X-MEDIA-SEQUENCE, fetches each segment (optionally decrypting AES-128), stores them in the existing HLS segment system, and
@@ -20,20 +19,64 @@ import { resolveUrl } from "./probe.js";
  * it preserves all playback-critical tags from the upstream manifest so that downstream consumers (Channels DVR) can correctly handle PTS resets at ad boundaries,
  * synchronize wall-clock time, and detect commercial breaks.
  *
- * Video segments are stored as "segment0.ts", "segment1.ts", etc. For streams with separate audio renditions, audio segments are stored as "audio0.ts",
- * "audio1.ts", etc.
+ * Segment names carry the container. An MPEG-TS source stores "segment0.ts", "segment1.ts", and so on, with "audio0.ts" upward for a separate audio rendition.
+ * An fMP4/CMAF source stores ".m4s" fragments under the same numbering, and the proxy additionally fetches the initialization segments its #EXT-X-MAP tags
+ * reference, serves them under names it mints per track, and emits the matching MAP references in every playlist it generates.
  */
 // Timeout for segment fetches.
 const SEGMENT_FETCH_TIMEOUT = 10000;
 // Maximum consecutive manifest poll failures before reporting an error. Client errors (4xx) use this threshold directly. Server errors (5xx) and network timeouts
 // use double the threshold to tolerate transient CDN issues that typically self-resolve within a few retry cycles.
 const MAX_MANIFEST_FAILURES = 3;
-// Maximum consecutive segment fetch failures before reporting an error.
+// Maximum consecutive tracked fetch failures before reporting an error. This governs media segments and the initialization segments an fMP4 source's #EXT-X-MAP
+// tags reference, since both ride the same tracker. Those fetches are smaller and far more numerous than manifest polls, so isolated transient failures (a
+// dropped connection on one segment) are more common here; this higher tolerance than MAX_MANIFEST_FAILURES avoids escalating on blips that would otherwise
+// self-resolve on the next fetch.
 const MAX_SEGMENT_FAILURES = 5;
-// Manifest poll backoff base delay and cap. On success, the poll interval returns to the base delay (half the target duration, typically ~3s). On failure, the delay
+// Number of segment byte-fetches one track keeps in flight while its commit walk consumes the results in broadcast order. Three concurrent connections lift a
+// track's download throughput to roughly three times the per-connection pacing a CDN edge grants, which is what keeps a high-bitrate channel ahead of its own
+// production rate rather than accumulating a backlog that delays the next manifest poll. The bound is what keeps the gain cheap: at most three segments per
+// track are resident at once - six for a stream whose audio is a separate rendition, since each track runs its own window.
+const PARALLEL_SEGMENT_FETCHES = 3;
+// Manifest poll backoff base delay and cap. On success, the poll interval returns to the base delay (a fixed 3000ms, ~half a typical 6s segment). On failure, the delay
 // doubles on each consecutive failure up to the cap. Jitter of +/-20% prevents multiple streams from retrying in lockstep after a shared CDN outage.
 const MANIFEST_BACKOFF_BASE = 3000;
 const MANIFEST_BACKOFF_CAP = 15000;
+/**
+ * Computes the consecutive-failure threshold for a manifest poll based on the HTTP status of the most recent failure. Client errors (4xx) typically indicate
+ * permanent issues (auth expiry, content removed) that won't self-resolve, so they use the base threshold directly. Server errors (5xx), network errors, and
+ * timeouts are transient CDN conditions that usually recover within a few retry cycles, so they get double the attempts. A missing status (network error, DNS
+ * failure, connection reset, timeout) is treated as transient. This is the single source of truth for the 4xx-versus-else threshold decision across every
+ * manifest-poll call site - video and audio, success-path and catch-path failure handlers alike - so audio and video share identical escalation logic.
+ *
+ * @param status - The HTTP status code of the failed response, or undefined for network/timeout errors that never produced a response.
+ * @returns The consecutive-failure threshold to compare against before reporting an error.
+ */
+export function manifestFailureThreshold(status) {
+    const isClientError = (status !== undefined) && (status >= 400) && (status < 500);
+    return isClientError ? MAX_MANIFEST_FAILURES : (MAX_MANIFEST_FAILURES * 2);
+}
+/**
+ * Resolves the initialization vector for a segment from the manifest's explicit IV (when present) or the media sequence number (when absent), per RFC 8216
+ * Section 5.2. When the manifest provides an explicit IV in the #EXT-X-KEY tag, it is authoritative and must parse cleanly: a malformed explicit IV is rejected
+ * rather than silently substituted with the sequence-derived IV. Substituting would decrypt the segment with the wrong IV, yielding corrupted CBC output on the
+ * first block - plausible-looking but garbage video served silently. Rejecting lets the caller count a fetch failure so recovery can escalate. The genuine absence
+ * of an explicit IV (ivHex === null) is the only case that derives the IV from the sequence number.
+ *
+ * @param ivHex - The explicit IV hex string from the manifest, or null when the manifest declares no explicit IV.
+ * @param sequence - The media sequence number used to derive the IV when no explicit IV is provided.
+ * @returns An "ok" result carrying the resolved IV, or a "reject" result when an explicit IV was provided but failed to parse.
+ */
+export function resolveSegmentIv(ivHex, sequence) {
+    if (ivHex !== null) {
+        const explicitIv = parseExplicitIv(ivHex);
+        if (!explicitIv) {
+            return { status: "reject" };
+        }
+        return { iv: explicitIv, status: "ok" };
+    }
+    return { iv: deriveIvFromSequence(sequence), status: "ok" };
+}
 // Manifest Parsing Helpers.
 /**
  * Parses a variant manifest into its metadata and segment list. Handles #EXT-X-MEDIA-SEQUENCE, #EXT-X-TARGETDURATION, #EXT-X-KEY (AES-128 with key rotation),
@@ -67,6 +110,10 @@ function parseVariantManifest(body, baseUrl) {
     let currentSequence = mediaSequence;
     let currentManifestKeyUrl = null;
     let currentIvHex = null;
+    // The initialization segment currently in force, tracked exactly like the key above: an #EXT-X-MAP applies to every following segment until another replaces
+    // it. This is per-document by design - the caller carries the cross-poll state, because a document that omits MAP entirely must leave the track's existing
+    // initialization untouched rather than reset it.
+    let currentMapUri = null;
     // Pending metadata flags - accumulated from tags between segments and attached to the next #EXTINF.
     let pendingCueIn = false;
     let pendingCueOut = null;
@@ -82,7 +129,13 @@ function parseVariantManifest(body, baseUrl) {
                 if (uri) {
                     currentManifestKeyUrl = resolveUrl(uri, baseUrl);
                 }
-                currentIvHex = /IV=([0-9a-fA-Fx]+)/.exec(trimmed)?.[1] ?? null;
+                // A quoted attribute value - most often the URI - may legally contain commas and arbitrary text, including a literal "IV=" sequence, so no attribute regex
+                // may scan across one. We blank every quoted span to an empty "" before scanning for the IV attribute, while the URI extraction above still reads the
+                // original line. The [:,] boundary ties IV= to the start of an attribute, right after the tag colon or a separating comma, so a coincidental attribute-name
+                // suffix such as FOOIV= cannot match, and the \s* tolerates the whitespace-after-comma layout some services emit. The capture takes the raw attribute value
+                // and defers every format judgment - the 0x or 0X prefix and the 32-hex length - to parseExplicitIv, the single owner of IV format rules.
+                const attributeResidue = trimmed.replace(/"[^"]*"/g, "\"\"");
+                currentIvHex = /[:,]\s*IV=([^,\s]+)/.exec(attributeResidue)?.[1] ?? null;
             }
             else if (method === "NONE") {
                 currentManifestKeyUrl = null;
@@ -90,6 +143,15 @@ function parseVariantManifest(body, baseUrl) {
             }
             continue;
         }
+        if (trimmed.startsWith("#EXT-X-MAP:")) {
+            // The URI attribute is extracted with the same quoted-attribute pattern the key handler uses. A MAP tag without a parseable URI leaves the current
+            // initialization in force rather than clearing it, matching how the key handler treats a URI-less AES-128 tag.
+            const uri = /URI="([^"]+)"/.exec(trimmed)?.[1];
+            if (uri) {
+                currentMapUri = resolveUrl(uri, baseUrl);
+            }
+            continue;
+        }
         if (trimmed === "#EXT-X-DISCONTINUITY") {
             pendingDiscontinuity = true;
             continue;
@@ -131,6 +193,7 @@ function parseVariantManifest(body, baseUrl) {
             duration,
             ivHex: currentIvHex,
             keyUrl: currentManifestKeyUrl,
+            mapUri: currentMapUri,
             programDateTime: pendingProgramDateTime,
             sequence: currentSequence,
             url: resolveUrl(segUrl, baseUrl)
@@ -156,11 +219,13 @@ function parseVariantManifest(body, baseUrl) {
  * @returns The formatted m3u8 playlist string.
  */
 function buildVariantPlaylist(segmentEntries, metadata, prefix, targetDuration) {
-    // Compute MEDIA-SEQUENCE from the first filename in the window. The filename encodes the local segment index (e.g., "segment5.ts" -> 5).
+    // Compute MEDIA-SEQUENCE from the first filename in the window. The filename encodes the local segment index between the prefix and the extension (e.g.,
+    // "segment5.ts" or "segment5.m4s" -> 5). The index is read by slicing to the final dot rather than stripping a specific extension, so the derivation holds for
+    // every container the relay names - stripping a hardcoded ".ts" would leave "5.m4s" and yield NaN for an fMP4 source.
     let mediaSequence = 0;
     const firstEntry = segmentEntries[0];
     if (firstEntry) {
-        mediaSequence = Number(firstEntry.replace(prefix, "").replace(".ts", ""));
+        mediaSequence = Number(firstEntry.slice(prefix.length, firstEntry.lastIndexOf(".")));
     }
     // Compute DISCONTINUITY-SEQUENCE: total discontinuities ever observed minus those still visible in the current window. Only provided when > 0 to keep playlists
     // clean for streams that never have discontinuities.
@@ -173,7 +238,12 @@ function buildVariantPlaylist(segmentEntries, metadata, prefix, targetDuration)
     const discSeq = metadata.totalDiscontinuities - windowDiscontinuities;
     const discontinuitySequence = (discSeq > 0) ? discSeq : undefined;
     const entries = segmentEntries.map((filename) => buildEntryFromMetadata(filename, metadata, targetDuration));
-    return buildPlaylist({ discontinuitySequence, mediaSequence, targetDuration, version: 3 }, entries);
+    // Place the MAP references through the shared chokepoint. Version 7 is required whenever a MAP appears anywhere in the window - as the opening reference or as
+    // a mid-window transition - because EXT-X-MAP is a version 6+ tag; an MPEG-TS window has neither and stays at version 3.
+    const initialMapUri = annotateMapTransitions(entries, metadata);
+    const hasTransition = entries.some((entry) => entry.mapUri !== undefined);
+    const version = ((initialMapUri !== null) || hasTransition) ? 7 : 3;
+    return buildPlaylist({ discontinuitySequence, initialMapUri: initialMapUri ?? undefined, mediaSequence, targetDuration, version }, entries);
 }
 /**
  * Creates an empty SegmentMetadata instance with fresh Maps and a zeroed discontinuity counter.
@@ -186,6 +256,7 @@ function createSegmentMetadata() {
         cueOuts: new Map(),
         discontinuities: new Map(),
         durations: new Map(),
+        mapUris: new Map(),
         timestamps: new Map(),
         totalDiscontinuities: 0
     };
@@ -197,9 +268,13 @@ function createSegmentMetadata() {
  * @param meta - The metadata instance to update.
  * @param filename - The local segment filename (e.g., "segment0.ts").
  * @param seg - The parsed segment with upstream metadata.
+ * @param servedInitName - The served initialization segment name this segment requires, or null for a self-describing MPEG-TS segment.
  */
-function storeSegmentMetadata(meta, filename, seg) {
+function storeSegmentMetadata(meta, filename, seg, servedInitName = null) {
     meta.durations.set(filename, seg.duration);
+    if (servedInitName !== null) {
+        meta.mapUris.set(filename, servedInitName);
+    }
     if (seg.programDateTime) {
         meta.timestamps.set(filename, seg.programDateTime);
     }
@@ -251,6 +326,112 @@ function buildEntryFromMetadata(filename, metadata, defaultDuration) {
     }
     return entry;
 }
+/**
+ * Places #EXT-X-MAP transition markers across a window of playlist entries and reports the initialization segment the window opens with. Every playlist the
+ * relay emits routes its MAP placement through here, so the variant and composite builders cannot drift on where a MAP belongs.
+ *
+ * An entry carries its own filename as its url, so the metadata lookup needs no parallel array. Only transitions are marked: the first entry's initialization
+ * becomes the window-level reference the caller emits as initialMapUri, and thereafter an entry gets a per-entry mapUri only when its initialization differs
+ * from its predecessor's. Stamping every entry would be legal but would defeat a client's ability to see where the codec configuration actually changes, and an
+ * MPEG-TS window - where no entry has an initialization at all - correctly produces neither.
+ *
+ * @param entries - The window's playlist entries, mutated in place to carry transition markers.
+ * @param metadata - The metadata instance holding each stored segment's served initialization name.
+ * @returns The initialization segment the window opens with, or null when the window's first entry needs none.
+ */
+function annotateMapTransitions(entries, metadata) {
+    let previousInit = null;
+    let initialMapUri = null;
+    for (const [index, entry] of entries.entries()) {
+        const servedInit = metadata.mapUris.get(entry.url) ?? null;
+        if (index === 0) {
+            initialMapUri = servedInit;
+        }
+        else if ((servedInit !== null) && (servedInit !== previousInit)) {
+            entry.mapUri = servedInit;
+        }
+        previousInit = servedInit;
+    }
+    return initialMapUri;
+}
+/**
+ * Replaces the contents of a key-URL Set with the distinct AES-128 key URLs referenced by the segments of a freshly-parsed manifest. The Set is rebuilt from
+ * scratch on each poll so it always reflects exactly the keys the current manifest window references - never a stale accumulation. The video and audio paths each
+ * own one such Set; their union is the live working set the per-URL key cache prunes against at token-refresh boundaries, which bounds the cache to the keys the
+ * stream is actually using rather than every key it has ever rotated through.
+ *
+ * @param target - The Set to rebuild in place.
+ * @param segments - The parsed segments whose key URLs (when present) define the new active set.
+ */
+function refreshActiveKeyUrls(target, segments) {
+    target.clear();
+    for (const seg of segments) {
+        if (seg.keyUrl !== null) {
+            target.add(seg.keyUrl);
+        }
+    }
+}
+/**
+ * Evicts decryption keys whose URL is not in the active working set, mutating the cache in place. The cache is keyed by URL because each token rotation can
+ * reference a different key URL; without this prune, the cache accumulates one dead entry per rotation indefinitely. The active set is the union of the URLs the
+ * current video and audio manifests reference, so keys still in use survive while keys that rotated out of both manifests are released. Returns the number of
+ * entries evicted so the caller can decide whether to log. Extracted as a pure module-level function (no closure capture) so the eviction invariant is unit-testable
+ * in isolation from the polling loop.
+ *
+ * @param keysByUrl - The per-URL key cache to prune in place.
+ * @param activeKeyUrls - The union of key URLs referenced by the current video and audio manifests.
+ * @returns The number of cache entries evicted.
+ */
+export function pruneKeyCache(keysByUrl, activeKeyUrls) {
+    let evicted = 0;
+    for (const cachedKeyUrl of keysByUrl.keys()) {
+        if (!activeKeyUrls.has(cachedKeyUrl)) {
+            keysByUrl.delete(cachedKeyUrl);
+            evicted++;
+        }
+    }
+    return evicted;
+}
+/**
+ * Fetches, identifies, and stores the initialization segment a track has just transitioned to. Both the video and audio loops call this, so init handling has one
+ * implementation regardless of track.
+ *
+ * The fetch goes through the caller's tracked-fetch function with a null key URL, which makes it a plain fetch (the decrypt path gates on the key, and the
+ * sequence argument only feeds keyed-IV derivation). Riding that machinery is deliberate: the initialization fetch inherits the timeout, the consecutive-failure
+ * accounting, the reset on any success, and the existing escalation threshold, rather than introducing a second failure counter whose bound-and-reset semantics
+ * would have to be re-derived.
+ *
+ * Identity is content-based against everything the track still holds. A service that rotates a token through its MAP URI serves identical bytes under a new URL,
+ * and an ad break can alternate between two initializations; comparing bytes lets both reuse the name already being served instead of minting one whose data a
+ * client has. Only genuinely new bytes take the next name.
+ *
+ * On failure the upstream URI is deliberately not recorded, so the next poll cycle retries it and the caller's gate keeps dependent segments out of the window
+ * meanwhile. After the fetch resolves the lifecycle is re-checked: the capture fallback stops the proxy and then clears the init store, and a write landing after
+ * that clear would orphan itself permanently, because init pruning only ever runs from this poll loop.
+ *
+ * @param options - The context, the track and its bookkeeping state, the tracked-fetch function, and the upstream MAP URI to resolve.
+ */
+async function resolveTrackInit(options) {
+    const { ctx, fetchSegment, mapUri, track, tracking } = options;
+    const data = await fetchSegment(tracking.segmentTracker, mapUri, 0, null, null);
+    if (!data) {
+        LOG.debug("native:proxy", "Initialization segment fetch failed for %s (%s track, %s).", ctx.channelName, track, mapUri.slice(0, 80));
+        return;
+    }
+    if (ctx.lifecycle.stopped) {
+        return;
+    }
+    const existingName = findNamedInitSegment(ctx.streamId, track, data);
+    let servedName = existingName;
+    if (servedName === undefined) {
+        servedName = ((track === "video") ? "init-v" : "init-a") + String(tracking.initCounter) + ".mp4";
+        tracking.initCounter++;
+    }
+    storeNamedInitSegment(ctx.streamId, track, servedName, data);
+    tracking.lastUpstreamMapUri = mapUri;
+    LOG.debug("native:proxy", "Initialization segment %s for %s (%s track, %s bytes, %s).", (existingName === undefined) ? "stored as " + servedName :
+        "reused as " + servedName, ctx.channelName, track, data.length, mapUri.slice(0, 80));
+}
 /**
  * Prunes stale entries from a SegmentMetadata instance. Removes entries for segments that are no longer in the active segment set (evicted from the sliding window).
  * This prevents unbounded growth over hours of streaming.
@@ -266,10 +447,203 @@ function pruneMetadata(meta, activeSegments) {
             meta.cueOuts.delete(key);
             meta.discontinuities.delete(key);
             meta.durations.delete(key);
+            meta.mapUris.delete(key);
             meta.timestamps.delete(key);
         }
     }
 }
+/**
+ * Releases a track's initialization segments that nothing in its playlist window still references. The retain set is every initialization named by a stored
+ * segment plus the track's current one, so an initialization outlives its own transition exactly as long as a segment that needs it remains fetchable, and no
+ * longer. Pruning per track keeps the two tracks' lifetimes independent.
+ *
+ * @param streamId - The numeric stream ID.
+ * @param track - The track to prune.
+ * @param metadata - The track's segment metadata, holding each stored segment's served initialization name.
+ * @param windowFilenames - The segment filenames currently in the track's store.
+ */
+function pruneTrackInits(streamId, track, metadata, windowFilenames) {
+    const retain = new Set();
+    for (const filename of windowFilenames) {
+        const servedInit = metadata.mapUris.get(filename);
+        if (servedInit !== undefined) {
+            retain.add(servedInit);
+        }
+    }
+    const currentName = getStream(streamId)?.hls.currentInitNames[track];
+    if (currentName) {
+        retain.add(currentName);
+    }
+    pruneNamedInitSegments(streamId, track, retain);
+}
+// Segment Fetch Pipeline.
+/**
+ * Performs the terminal transition every escalation site shares: latch the error state the monitor reads, stop the poll loop, cancel every fetch the proxy
+ * still has open, and report the reason to the coordinator. Single-homed so no site can flip the flags while leaving fetches running on past the stop, and so
+ * the state the monitor reads has exactly one writer.
+ *
+ * @param options - The proxy context and the message the coordinator receives.
+ */
+function escalateProxyFailure(options) {
+    const { ctx, message } = options;
+    ctx.lifecycle.errorThresholdReached = true;
+    ctx.lifecycle.stopped = true;
+    ctx.lifecycle.abortController.abort();
+    ctx.onError(message);
+}
+/**
+ * Applies a settled fetch outcome to a track's failure accounting: a success clears the consecutive count, a failure raises it along with the cumulative error
+ * total, and crossing MAX_SEGMENT_FAILURES escalates. A cancellation touches neither counter - the proxy cancels its own fetches at teardown and at escalation,
+ * and counting those would make the termination summary report the stop's own casualties as fetches that failed. Single-homed here so the tracked fetch wrapper
+ * and the commit walk apply identical accounting to identical outcomes.
+ *
+ * @param options - The proxy context, the settled outcome, and the track's failure tracker.
+ */
+function recordFetchOutcome(options) {
+    const { ctx, outcome, tracker } = options;
+    if (outcome.status === "abort") {
+        return;
+    }
+    if (outcome.status === "success") {
+        tracker.consecutiveFailures = 0;
+        return;
+    }
+    // A thrown failure carries a cause worth narrating; the core's null failure has already logged whatever it knew at the point it gave up.
+    if (outcome.status === "failed-thrown") {
+        LOG.debug("native:proxy", "%s fetch failed for %s: %s.", tracker.debugLabel, ctx.channelName, String(outcome.error));
+    }
+    tracker.consecutiveFailures++;
+    ctx.stats.totalFetchErrors++;
+    if (tracker.consecutiveFailures >= MAX_SEGMENT_FAILURES) {
+        const detail = (outcome.status === "failed-thrown") ? " fetch error: " + String(outcome.error) :
+            " fetch failed " + String(tracker.consecutiveFailures) + " times";
+        escalateProxyFailure({ ctx, message: tracker.label + detail });
+    }
+}
+/**
+ * Starts one fetch and settles with its outcome, never rejecting. The cancellation signal's own state is the first thing read at settlement: when the proxy has
+ * aborted, the outcome is a cancellation whatever shape the settlement took, because a cancelled key fetch surfaces as a resolved null rather than as a
+ * rejection and the signal is the one place cancellation is unambiguous. With the signal unaborted, shape decides: a rejection is a failure, which is how a
+ * per-fetch timeout keeps counting as one, and a null return is the core's untyped failure. Every fetch the proxy starts settles through here, so no bare core
+ * promise is left for the process-level rejection handler to catch.
+ *
+ * @param options - The fetch to start and the proxy's cancellation signal.
+ * @returns The settled outcome.
+ */
+async function captureFetchOutcome(options) {
+    const { fetchSegment, signal } = options;
+    try {
+        const data = await fetchSegment();
+        if (signal.aborted) {
+            return { status: "abort" };
+        }
+        return data ? { data, status: "success" } : { status: "failed-null" };
+    }
+    catch (error) {
+        return signal.aborted ? { status: "abort" } : { error, status: "failed-thrown" };
+    }
+}
+/**
+ * Fetches a poll cycle's new segments and commits them in broadcast order. The walk over the batch is the ordered one the relay performs for every track: the
+ * initialization attempt at its transition, the unadopted skip, the container-true naming, the metadata, and the accounting all happen at the same points
+ * against the same state. What the scheduler adds is where the bytes come from - it runs ahead of the walk and keeps up to PARALLEL_SEGMENT_FETCHES byte-fetches
+ * open for the track, so the walk consumes results that are already settled or already downloading instead of opening each connection when it arrives. Download
+ * throughput therefore scales with the window while the served window still advances one segment at a time, in upstream order.
+ *
+ * A slot is occupied from the moment a fetch starts until the item that owns it has committed: the window is topped up only at the head of an iteration, which
+ * is after the previous item's store. Segments at or beyond an initialization transition the track has not adopted are never prefetched - the walk's own inline
+ * attempt is what decides whether they are fetchable at all, and starting them early would spend connections on bytes the adoption outcome can make unusable.
+ *
+ * @param options - The proxy context, the cycle's new segments in upstream order, and the track's pipeline binding.
+ * @returns True if at least one segment was stored.
+ */
+async function runSegmentPipeline(options) {
+    const { ctx, segments, track } = options;
+    const { lifecycle } = ctx;
+    const tracking = track.tracking;
+    const inFlight = new Map();
+    // The next batch item the scheduler may start. It advances as fetches begin, and the walk carries it past any item it skips, so a batch that returns to the
+    // adopted initialization after an unresolved transition still prefetches its remainder.
+    let dispatchIndex = 0;
+    // At most one initialization fetch per track per poll cycle. A function-scoped local is the whole mechanism: it cannot outlive the cycle, cannot be
+    // forgotten, and cannot be shared with the other track, whose own pipeline call declares its own. One failing upstream initialization therefore costs one
+    // fetch timeout per cycle rather than one per dependent segment.
+    let initAttempted = false;
+    let storedAny = false;
+    /* Tops the window up to PARALLEL_SEGMENT_FETCHES open fetches, each started against the proxy's cancellation signal and wrapped so it settles rather than
+     * rejects. Eligibility is read against the walk's adoption state as it stands at this moment, so the scheduler stops at the first segment declaring an
+     * initialization the track has not adopted and resumes from there once the walk's inline attempt has settled that transition.
+     */
+    const fillWindow = () => {
+        while ((inFlight.size < PARALLEL_SEGMENT_FETCHES) && (dispatchIndex < segments.length) && !lifecycle.stopped) {
+            const segment = segments[dispatchIndex];
+            if (!segment || ((segment.mapUri !== null) && (segment.mapUri !== tracking.lastUpstreamMapUri))) {
+                return;
+            }
+            inFlight.set(dispatchIndex, captureFetchOutcome({ fetchSegment: () => track.fetchSegment(segment), signal: lifecycle.abortController.signal }));
+            dispatchIndex++;
+        }
+    };
+    for (const [index, segment] of segments.entries()) {
+        if (lifecycle.stopped) {
+            break;
+        }
+        // Resolve this segment's initialization before its name is chosen, so the first segment of a fresh tune is named from the initialization its own document
+        // established rather than transiently mislabeled.
+        if ((segment.mapUri !== null) && (segment.mapUri !== tracking.lastUpstreamMapUri) && !initAttempted) {
+            initAttempted = true;
+            // The attempt is sequential by contract: its outcome decides whether the rest of the batch is fetchable at all, so the walk holds here rather than
+            // running ahead of an adoption that has not happened.
+            // eslint-disable-next-line no-await-in-loop
+            await resolveTrackInit({ ctx, fetchSegment: track.fetchInit, mapUri: segment.mapUri, track: track.initTrack, tracking });
+        }
+        /* Store only segments whose initialization is resolved. A segment declaring a MAP the track has not adopted is skipped whether this cycle's attempt at that
+         * URI failed or the cycle's one attempt went to a different transition earlier in the window. Naming never falls back to the track's current initialization
+         * for a segment whose own transition is unresolved, so a second distinct transition in one batch cannot be mislabeled with the first one's initialization.
+         * The cost is bounded: each additional distinct transition in a batch resolves one cycle later.
+         */
+        if ((segment.mapUri !== null) && (segment.mapUri !== tracking.lastUpstreamMapUri)) {
+            // Carry the scheduler past an item that will not be fetched at all, so a later segment back under the adopted initialization is still prefetched.
+            dispatchIndex = index + 1;
+            continue;
+        }
+        fillWindow();
+        const pending = inFlight.get(index);
+        if (!pending) {
+            // The window declines to start a fetch once the proxy is stopping, which is the only way the walk reaches an item with nothing open for it.
+            break;
+        }
+        // Commits are sequential by contract - the served window advances one segment at a time, in upstream order - while the fetches the scheduler started ahead
+        // of this point keep running concurrently. Waiting here is what the commit ordering costs, and it costs nothing in download time.
+        // eslint-disable-next-line no-await-in-loop
+        const outcome = await pending;
+        inFlight.delete(index);
+        // Every outcome the walk consumes goes through the one accounting helper, cancellations included - it is the helper that decides a cancellation counts as
+        // neither a success nor a failure, and that decision is made in exactly one place.
+        recordFetchOutcome({ ctx, outcome, tracker: tracking.segmentTracker });
+        if (outcome.status === "abort") {
+            // Only teardown and escalation cancel, and both have already stopped the loop, so the rest of the batch goes with this item.
+            break;
+        }
+        if (outcome.status !== "success") {
+            continue;
+        }
+        // Name by container. A track holding an initialization is fMP4 and its fragments are .m4s; a track with none is MPEG-TS and keeps .ts.
+        const servedInit = getStream(ctx.streamId)?.hls.currentInitNames[track.initTrack] ?? null;
+        const filename = track.filenamePrefix + String(tracking.segmentIndex) + ((servedInit !== null) ? ".m4s" : ".ts");
+        const storedBefore = track.countStored(ctx.streamId);
+        track.store(ctx.streamId, filename, outcome.data);
+        tracking.fetchedSequences.add(segment.sequence);
+        tracking.highWaterSequence = Math.max(tracking.highWaterSequence, segment.sequence);
+        storeSegmentMetadata(tracking.metadata, filename, segment, servedInit);
+        storedAny = true;
+        tracking.segmentIndex++;
+        ctx.stats.totalSegmentsFetched++;
+        track.afterCommit?.({ byteLength: outcome.data.length, filename, storedBefore });
+        LOG.debug("native:proxy", "Stored %s (%s bytes, seq %s) for %s.", filename, outcome.data.length, segment.sequence, ctx.channelName);
+    }
+    return storedAny;
+}
 // Audio Stream Handler.
 /**
  * Polls the audio variant manifest and fetches new audio segments. Combines the audio manifest poll and segment processing into a single entry point that mirrors the
@@ -277,10 +651,10 @@ function pruneMetadata(meta, activeSegments) {
  *
  * @param ctx - Shared proxy context with lifecycle state, stats, channel name, and error callback.
  * @param audio - Audio-specific tracking state (sequence tracking, metadata, failure counters).
- * @param fetchSegment - Closure-bound segment fetch function that handles HTTP fetch, decryption, and error tracking.
+ * @param pipeline - The audio track's pipeline binding: its fetch callbacks, store, naming, and bookkeeping.
  * @returns True if new audio segments were stored, false otherwise.
  */
-async function pollAudioStream(ctx, audio, fetchSegment) {
+async function pollAudioStream(ctx, audio, pipeline) {
     if (ctx.lifecycle.stopped || !audio.variantUrl) {
         return false;
     }
@@ -289,26 +663,28 @@ async function pollAudioStream(ctx, audio, fetchSegment) {
         if (!response.ok) {
             audio.consecutiveManifestFailures++;
             ctx.stats.totalFetchErrors++;
-            LOG.debug("native:proxy", "Audio manifest poll failed for %s: HTTP %s.", ctx.channelName, response.status);
-            if (audio.consecutiveManifestFailures >= MAX_MANIFEST_FAILURES) {
-                ctx.lifecycle.errorThresholdReached = true;
-                ctx.lifecycle.stopped = true;
-                ctx.onError("audio manifest poll failed " + String(audio.consecutiveManifestFailures) + " times");
+            // Classify the failure via the shared threshold helper so the audio path escalates identically to the video path: 4xx uses the base threshold, 5xx and
+            // network conditions get double the attempts.
+            const effectiveThreshold = manifestFailureThreshold(response.status);
+            LOG.debug("native:proxy", "Audio manifest poll failed for %s: HTTP %s (%s/%s).", ctx.channelName, response.status, audio.consecutiveManifestFailures, effectiveThreshold);
+            if (audio.consecutiveManifestFailures >= effectiveThreshold) {
+                escalateProxyFailure({ ctx, message: "audio manifest poll failed " + String(audio.consecutiveManifestFailures) + " times" });
             }
             return false;
         }
         audio.consecutiveManifestFailures = 0;
         const body = await response.text();
-        return await processAudioStream(ctx, audio, body, audio.variantUrl, fetchSegment);
+        return await processAudioStream(ctx, audio, body, audio.variantUrl, pipeline);
     }
     catch (error) {
+        // Network errors (timeouts, DNS failures, connection resets) are transient - the threshold helper returns the doubled value for a missing status, matching the
+        // video catch path so audio and video escalate identically.
         audio.consecutiveManifestFailures++;
         ctx.stats.totalFetchErrors++;
-        LOG.debug("native:proxy", "Audio manifest poll failed for %s: %s.", ctx.channelName, String(error));
-        if (audio.consecutiveManifestFailures >= MAX_MANIFEST_FAILURES) {
-            ctx.lifecycle.errorThresholdReached = true;
-            ctx.lifecycle.stopped = true;
-            ctx.onError("audio manifest poll error: " + String(error));
+        const networkThreshold = manifestFailureThreshold();
+        LOG.debug("native:proxy", "Audio manifest poll failed for %s: %s (%s/%s).", ctx.channelName, String(error), audio.consecutiveManifestFailures, networkThreshold);
+        if (audio.consecutiveManifestFailures >= networkThreshold) {
+            escalateProxyFailure({ ctx, message: "audio manifest poll error: " + String(error) });
         }
         return false;
     }
@@ -321,12 +697,15 @@ async function pollAudioStream(ctx, audio, fetchSegment) {
  * @param audio - Audio-specific tracking state.
  * @param body - The audio variant manifest text content.
  * @param baseUrl - The audio variant URL for resolving relative segment URLs.
- * @param fetchSegment - Closure-bound segment fetch function.
+ * @param pipeline - The audio track's pipeline binding: its fetch callbacks, store, naming, and bookkeeping.
  * @returns True if new segments were stored, false if the media sequence hadn't advanced.
  */
-async function processAudioStream(ctx, audio, body, baseUrl, fetchSegment) {
+async function processAudioStream(ctx, audio, body, baseUrl, pipeline) {
     const { mediaSequence, segments, targetDuration } = parseVariantManifest(body, baseUrl);
     audio.lastTargetDuration = targetDuration;
+    // Record the AES-128 key URLs the current audio manifest references so the per-URL key cache can prune against the live video+audio working set on the next
+    // token refresh, rather than retaining a key per rotation indefinitely.
+    refreshActiveKeyUrls(audio.activeKeyUrls, segments);
     // Prune old entries from audio fetchedSequences and audio metadata on each poll cycle.
     for (const seq of audio.fetchedSequences) {
         if (seq < mediaSequence) {
@@ -357,34 +736,15 @@ async function processAudioStream(ctx, audio, body, baseUrl, fetchSegment) {
         return false;
     }
     LOG.debug("native:proxy", "Fetching %s new audio segment(s) for %s (sequence %s).", newSegments.length, ctx.channelName, mediaSequence);
-    let storedAny = false;
-    for (const seg of newSegments) {
-        if (ctx.lifecycle.stopped) {
-            break;
-        }
-        // eslint-disable-next-line no-await-in-loop
-        const segmentData = await fetchSegment(audio.segmentTracker, seg.url, seg.sequence, seg.ivHex, seg.keyUrl);
-        if (!segmentData) {
-            continue;
-        }
-        const filename = "audio" + String(audio.segmentIndex) + ".ts";
-        storeAudioSegment(ctx.streamId, filename, segmentData);
-        audio.fetchedSequences.add(seg.sequence);
-        audio.highWaterSequence = Math.max(audio.highWaterSequence, seg.sequence);
-        storeSegmentMetadata(audio.metadata, filename, seg);
-        storedAny = true;
-        audio.segmentIndex++;
-        ctx.stats.totalSegmentsFetched++;
-        LOG.debug("native:proxy", "Stored %s (%s bytes, seq %s) for %s.", filename, segmentData.length, seg.sequence, ctx.channelName);
-    }
-    return storedAny;
+    return await runSegmentPipeline({ ctx, segments: newSegments, track: pipeline });
 }
 // Composite Playlist Builder.
 /**
- * Builds a composite playlist with fMP4 preroll entries and MPEG-TS real entries. Uses the same compositor and builder as the capture path's generatePlaylist(),
- * ensuring identical windowing behavior (maxPrerollInWindow cap, progressive falloff). The DISCONTINUITY tag at the preroll-to-real boundary signals the container
- * format change (fMP4 -> MPEG-TS), which is spec-compliant per RFC 8216 Section 4.3.3.3. VERSION:7 is used to support EXT-X-MAP for the preroll init segment;
- * after preroll entries fall off the window, VERSION:7 remains but is backward-compatible with the MPEG-TS entries.
+ * Builds a composite playlist with fMP4 preroll entries and the relayed source's real entries. Uses the same compositor and builder as the capture path's
+ * generatePlaylist(), ensuring identical windowing behavior (maxPrerollInWindow cap, progressive falloff). The DISCONTINUITY tag at the preroll-to-real boundary
+ * signals the transition between two independently-initialized runs of content, which is spec-compliant per RFC 8216 Section 4.3.3.3 - and when the relayed
+ * source is itself fMP4, that boundary is also where its own initialization reference is re-emitted. VERSION:7 is used throughout to support EXT-X-MAP, and stays
+ * backward-compatible with MPEG-TS entries once preroll falls off the window.
  *
  * @param options - Composite playlist configuration with segment data, preroll settings, and composite tracking state.
  * @returns The formatted composite m3u8 playlist string.
@@ -438,10 +798,24 @@ function buildCompositePlaylist(options) {
     }
     const discSeq = (composite.baseOffset + composite.discontinuities.size) - windowDiscontinuities;
     const discontinuitySequence = (discSeq > 0) ? discSeq : undefined;
-    // Determine the initial MAP URI. When the window starts with preroll entries, the preroll init segment (fMP4) is referenced. When the window has moved past all
-    // preroll, no MAP is needed (MPEG-TS segments are self-describing). The DISCONTINUITY tag at the preroll-to-real boundary invalidates the MAP per RFC 8216
-    // Section 4.3.3.3, so MPEG-TS entries after the boundary carry their codec config inline.
-    const initialMapUri = (prerollEntries.length > 0) ? (prerollBaseUrl + "/preroll/" + prerollCodec + "/init.mp4") : undefined;
+    /* Determine the MAP references. Two initialization regimes can meet in this one window: the fMP4 preroll's own init, and whatever the relayed source needs.
+     *
+     * The real entries are annotated through the same chokepoint the variant playlist uses, which reports the initialization the real content opens with - null
+     * for an MPEG-TS tail, whose segments are self-describing. When preroll occupies the head of the window, the window-level reference must stay the preroll
+     * init, so a non-null real-content initialization is redirected onto the first real entry: the DISCONTINUITY already marked at that boundary invalidates the
+     * preroll MAP per RFC 8216 Section 4.3.3.3, and the redirected reference is what re-establishes codec configuration for the content that follows. Once preroll
+     * has fallen out of the window, the real content's own initialization becomes the window-level reference directly.
+     */
+    const realInitialMapUri = annotateMapTransitions(realEntries, videoMetadata);
+    let initialMapUri = (prerollEntries.length > 0) ? (prerollBaseUrl + "/preroll/" + prerollCodec + "/init.mp4") : undefined;
+    if (realInitialMapUri !== null) {
+        if ((prerollEntries.length > 0) && firstRealEntry) {
+            firstRealEntry.mapUri = realInitialMapUri;
+        }
+        else {
+            initialMapUri = realInitialMapUri;
+        }
+    }
     return buildPlaylist({
         discontinuitySequence,
         initialMapUri,
@@ -457,9 +831,8 @@ function buildCompositePlaylist(options) {
  * @returns The native proxy interface.
  */
 export function createNativeProxy(options) {
-    const { channelName, clock = realClock, encryption, keyUrl, onError, streamId } = options;
+    const { channelName, clock = realClock, container, encryption, keyUrl, onError, streamId } = options;
     const hasAudio = options.audioVariantUrl !== null;
-    let activeCdpSession = options.cdpSession;
     // Preroll segment index offset. When preroll is ready (prerollSegmentCount > 0), real segments start numbering after the preroll range (e.g., segmentN.ts where
     // N = prerollSegmentCount). This offset is unconditional - it reserves the index space for preroll regardless of whether the deferred preroll timer fires.
     // The composite playlist behavior (including preroll entries) is determined dynamically by checking stream.hls.prerollStartTime at playlist generation time.
@@ -471,22 +844,28 @@ export function createNativeProxy(options) {
      */
     // Proxy lifecycle state. Controls whether the proxy is running, tracks readiness signaling, and manages poll timing.
     const lifecycle = {
+        abortController: new AbortController(),
         errorThresholdReached: false,
         firstPollComplete: false,
         manifestBackoffMs: MANIFEST_BACKOFF_BASE,
+        pendingRefresh: null,
         readinessSignaled: false,
+        refreshFailureCount: 0,
         stopped: false,
         tokenRefreshTimer: null
     };
     // Video segment and manifest tracking state.
     const video = {
+        activeKeyUrls: new Set(),
         consecutiveManifestFailures: 0,
         fetchedSequences: new Set(),
         highWaterSequence: -1,
+        initCounter: 0,
         lastMediaSequence: -1,
         lastSegmentSize: null,
         lastSegmentTime: 0,
         lastTargetDuration: 6,
+        lastUpstreamMapUri: null,
         metadata: createSegmentMetadata(),
         segmentIndex: prerollSegmentCount,
         segmentTracker: { consecutiveFailures: 0, debugLabel: "Segment", label: "segment" },
@@ -495,10 +874,13 @@ export function createNativeProxy(options) {
     };
     // Audio segment and manifest tracking state for streams with separate audio renditions.
     const audio = {
+        activeKeyUrls: new Set(),
         consecutiveManifestFailures: 0,
         fetchedSequences: new Set(),
         highWaterSequence: -1,
+        initCounter: 0,
         lastTargetDuration: 6,
+        lastUpstreamMapUri: null,
         metadata: createSegmentMetadata(),
         segmentIndex: 0,
         segmentTracker: { consecutiveFailures: 0, debugLabel: "Audio segment", label: "audio segment" },
@@ -523,12 +905,60 @@ export function createNativeProxy(options) {
     };
     // Shared context for extracted module-level functions. Bundles immutable references with shared mutable state objects.
     const ctx = { channelName, lifecycle, onError, stats, streamId };
+    /* The two tracks' pipeline bindings. Construction happens here, at the proxy's composition root, so the pipeline that serves both loops carries no branch on
+     * which track it is running: everything that differs between them - where segments are stored, how many are stored, how they are named, which initialization
+     * slot they read, and the extra bookkeeping video alone keeps - is data on these two objects.
+     */
+    const videoPipeline = {
+        afterCommit: ({ byteLength, storedBefore }) => {
+            video.lastSegmentSize = byteLength;
+            video.lastSegmentTime = Date.now();
+            // Log the first segment fetch latency for timing diagnostics.
+            if (stats.totalSegmentsFetched === 1) {
+                LOG.debug("timing:native", "First segment fetched for %s (%s bytes).", channelName, byteLength);
+            }
+            // Detect segment rotation - if the count didn't increase, the oldest segment was evicted.
+            const storedAfter = getStream(streamId)?.hls.segments.size ?? 0;
+            if ((storedAfter <= storedBefore) && (storedBefore > 0)) {
+                LOG.debug("native:proxy", "Segment rotated for %s (oldest removed, %s segments retained).", channelName, storedAfter);
+            }
+        },
+        countStored: (id) => getStream(id)?.hls.segments.size ?? 0,
+        fetchInit: fetchTrackedSegment,
+        fetchSegment: prefetchSegment,
+        filenamePrefix: "segment",
+        initTrack: "video",
+        store: storeSegment,
+        tracking: video
+    };
+    const audioPipeline = {
+        countStored: (id) => getStream(id)?.hls.audioSegments.size ?? 0,
+        fetchInit: fetchTrackedSegment,
+        fetchSegment: prefetchSegment,
+        filenamePrefix: "audio",
+        initTrack: "audio",
+        store: storeAudioSegment,
+        tracking: audio
+    };
     // AES-128 decryption key cache. Maps key URLs to their fetched 16-byte keys. Each segment in a manifest can reference a different key URL (key rotation), so we
     // cache by URL rather than maintaining a single "current key". The coordinator pre-fetches the initial key, which is seeded into the cache here.
     const keysByUrl = new Map();
     if (options.prefetchedKey && keyUrl) {
         keysByUrl.set(keyUrl, options.prefetchedKey);
     }
+    /**
+     * Prunes the per-URL decryption key cache against this stream's live working set - the union of the key URLs the most recently polled video and audio manifests
+     * reference - and logs the eviction count. Called at each token-refresh boundary, this bounds the cache to the keys the stream is actually using (typically one or
+     * two) rather than retaining one dead entry per rotation. Refresh is the natural point at which the prior CDN session's keys become unreachable, so it runs here
+     * rather than on every poll. The eviction itself lives in the pure module-level pruneKeyCache so the invariant is unit-testable.
+     */
+    function pruneStreamKeyCache() {
+        const activeKeyUrls = new Set([...video.activeKeyUrls, ...audio.activeKeyUrls]);
+        const evicted = pruneKeyCache(keysByUrl, activeKeyUrls);
+        if (evicted > 0) {
+            LOG.debug("native:proxy", "Pruned %s stale decryption key(s) for %s (%s active).", evicted, channelName, keysByUrl.size);
+        }
+    }
     /**
      * Computes the next retry delay with exponential backoff and jitter. Doubles the current backoff (capped at MANIFEST_BACKOFF_CAP) and applies +/-20% jitter.
      * @returns The jittered delay in milliseconds.
@@ -551,15 +981,14 @@ export function createNativeProxy(options) {
             if (!response.ok) {
                 video.consecutiveManifestFailures++;
                 stats.totalFetchErrors++;
-                // Classify the error. Client errors (4xx) typically indicate permanent issues (auth expiry, content removed) that won't self-resolve. Server errors (5xx)
-                // are transient CDN issues that usually recover within a few seconds. Client errors use the base threshold; server errors get double the attempts.
+                // Classify the error via the shared threshold helper. Client errors (4xx) use the base threshold; server errors (5xx) and network conditions get double the
+                // attempts. This is the same logic the audio poll path uses, so video and audio escalate identically.
                 const isClientError = (response.status >= 400) && (response.status < 500);
-                const effectiveThreshold = isClientError ? MAX_MANIFEST_FAILURES : (MAX_MANIFEST_FAILURES * 2);
+                const effectiveThreshold = manifestFailureThreshold(response.status);
                 LOG.debug("native:proxy", "Manifest poll failed for %s: HTTP %s (%s, %s/%s).", channelName, response.status, isClientError ? "client" : "server", video.consecutiveManifestFailures, effectiveThreshold);
                 if (video.consecutiveManifestFailures >= effectiveThreshold) {
-                    lifecycle.errorThresholdReached = true;
-                    lifecycle.stopped = true;
-                    onError("manifest poll failed " + String(video.consecutiveManifestFailures) + " times (HTTP " + String(response.status) + ")");
+                    escalateProxyFailure({ ctx, message: "manifest poll failed " + String(video.consecutiveManifestFailures) + " times (HTTP " +
+                            String(response.status) + ")" });
                     return;
                 }
                 schedulePoll(nextBackoffDelay());
@@ -575,7 +1004,7 @@ export function createNativeProxy(options) {
             let hasNewVideoSegments;
             let hasNewAudioSegments = false;
             if (hasAudio) {
-                [hasNewVideoSegments, hasNewAudioSegments] = await Promise.all([processManifest(body), pollAudioStream(ctx, audio, fetchTrackedSegment)]);
+                [hasNewVideoSegments, hasNewAudioSegments] = await Promise.all([processManifest(body), pollAudioStream(ctx, audio, audioPipeline)]);
             }
             else {
                 hasNewVideoSegments = await processManifest(body);
@@ -591,8 +1020,9 @@ export function createNativeProxy(options) {
             if (!lifecycle.firstPollComplete && (video.segmentIndex > 0) && (!hasAudio || (audio.segmentIndex > 0))) {
                 lifecycle.firstPollComplete = true;
             }
-            // Signal playlist readiness after the first poll completes. Note: initSegmentReady is signaled immediately when the proxy starts (in hls.ts) since native
-            // MPEG-TS has no separate init segment.
+            // Signal playlist readiness after the first poll completes. Init readiness is a separate signal owned elsewhere: an MPEG-TS source has no separate
+            // initialization segment, so hls.ts signals it the moment the proxy starts, while an fMP4 source's signal comes from the store when this loop's first
+            // video initialization lands.
             if (lifecycle.firstPollComplete && !lifecycle.readinessSignaled) {
                 lifecycle.readinessSignaled = true;
                 const stream = getStream(streamId);
@@ -603,20 +1033,20 @@ export function createNativeProxy(options) {
             }
         }
         catch (error) {
-            // Network errors (timeouts, DNS failures, connection resets) are transient - use the extended threshold and backoff.
+            // Network errors (timeouts, DNS failures, connection resets) are transient - use the extended threshold and backoff. The threshold helper returns the doubled
+            // value for a missing status, which is exactly the network-error case here.
             video.consecutiveManifestFailures++;
             stats.totalFetchErrors++;
-            LOG.debug("native:proxy", "Manifest poll failed for %s: %s (%s/%s).", channelName, String(error), video.consecutiveManifestFailures, MAX_MANIFEST_FAILURES * 2);
-            if (video.consecutiveManifestFailures >= (MAX_MANIFEST_FAILURES * 2)) {
-                lifecycle.errorThresholdReached = true;
-                lifecycle.stopped = true;
-                onError("manifest poll error: " + String(error));
+            const networkThreshold = manifestFailureThreshold();
+            LOG.debug("native:proxy", "Manifest poll failed for %s: %s (%s/%s).", channelName, String(error), video.consecutiveManifestFailures, networkThreshold);
+            if (video.consecutiveManifestFailures >= networkThreshold) {
+                escalateProxyFailure({ ctx, message: "manifest poll error: " + String(error) });
                 return;
             }
             schedulePoll(nextBackoffDelay());
             return;
         }
-        // Schedule the next poll at roughly half the target segment duration for timely detection of new segments.
+        // Schedule the next poll at MANIFEST_BACKOFF_BASE (3000ms, ~half a typical 6s segment) for timely detection of new segments.
         lifecycle.manifestBackoffMs = MANIFEST_BACKOFF_BASE;
         schedulePoll(MANIFEST_BACKOFF_BASE);
     }
@@ -629,6 +1059,9 @@ export function createNativeProxy(options) {
     async function processManifest(body) {
         const { mediaSequence, segments, targetDuration } = parseVariantManifest(body, video.variantUrl);
         video.lastTargetDuration = targetDuration;
+        // Record the AES-128 key URLs the current video manifest references so the per-URL key cache can prune against the live video+audio working set on the next
+        // token refresh, rather than retaining a key per rotation indefinitely.
+        refreshActiveKeyUrls(video.activeKeyUrls, segments);
         // Prune old entries from the fetchedSequences Set and segment metadata on each poll cycle. The service's media sequence window slides forward, so entries below
         // the current base sequence will never be checked again. Without pruning, these structures grow unboundedly over hours of streaming.
         for (const seq of video.fetchedSequences) {
@@ -675,55 +1108,26 @@ export function createNativeProxy(options) {
         }
         LOG.debug("native:proxy", "Fetching %s new segment(s) for %s (sequence %s).", newSegments.length, channelName, mediaSequence);
         video.lastMediaSequence = mediaSequence;
-        // Fetch and store each new segment sequentially. Track whether at least one segment was stored so the caller only generates playlists when data actually changed.
-        let storedAny = false;
-        for (const seg of newSegments) {
-            if (lifecycle.stopped) {
-                break;
-            }
-            // eslint-disable-next-line no-await-in-loop
-            const segmentData = await fetchTrackedSegment(video.segmentTracker, seg.url, seg.sequence, seg.ivHex, seg.keyUrl);
-            if (!segmentData) {
-                continue;
-            }
-            const filename = "segment" + String(video.segmentIndex) + ".ts";
-            // Check segment count before store to detect rotation (oldest segment evicted to enforce maxSegments limit).
-            const stream = getStream(streamId);
-            const countBefore = stream?.hls.segments.size ?? 0;
-            storeSegment(streamId, filename, segmentData);
-            video.fetchedSequences.add(seg.sequence);
-            video.highWaterSequence = Math.max(video.highWaterSequence, seg.sequence);
-            storeSegmentMetadata(video.metadata, filename, seg);
-            storedAny = true;
-            video.lastSegmentSize = segmentData.length;
-            video.lastSegmentTime = Date.now();
-            video.segmentIndex++;
-            stats.totalSegmentsFetched++;
-            // Log the first segment fetch latency for timing diagnostics.
-            if (stats.totalSegmentsFetched === 1) {
-                LOG.debug("timing:native", "First segment fetched for %s (%s bytes).", channelName, segmentData.length);
-            }
-            // Detect segment rotation - if the count didn't increase, the oldest segment was evicted.
-            const countAfter = stream?.hls.segments.size ?? 0;
-            if ((countAfter <= countBefore) && (countBefore > 0)) {
-                LOG.debug("native:proxy", "Segment rotated for %s (oldest removed, %s segments retained).", channelName, countAfter);
-            }
-            LOG.debug("native:proxy", "Stored %s (%s bytes, seq %s) for %s.", filename, segmentData.length, seg.sequence, channelName);
-        }
-        return storedAny;
+        return await runSegmentPipeline({ ctx, segments: newSegments, track: videoPipeline });
     }
     /**
-     * Fetches and optionally decrypts a segment. This is the shared core used by both video and audio fetch paths. It handles the HTTP fetch, AES-128 decryption with
-     * key caching, and IV derivation. Error tracking is the caller's responsibility since video and audio have independent failure thresholds.
+     * Fetches and optionally decrypts a segment. This is the shared core used by both video and audio fetch paths, for media segments and for the initialization
+     * segments an fMP4 source references. It handles the HTTP fetch, AES-128 decryption with key caching, and IV derivation. A caller with no key URL gets a plain
+     * fetch, since the decryption block below gates on the key and the sequence argument only feeds keyed-IV derivation. Error tracking is the caller's
+     * responsibility since video and audio have independent failure thresholds.
      *
      * @param url - The segment URL.
      * @param sequence - The media sequence number (for IV derivation).
      * @param ivHex - Explicit IV hex string from the manifest, or null.
      * @param segKeyUrl - The key URL for this specific segment from the manifest's #EXT-X-KEY tag, or null for clear segments.
+     * @param abortSignal - Optional cancellation signal, composed with this fetch's own timeout.
      * @returns The segment data (decrypted if necessary), or null on failure.
      */
-    async function fetchAndDecryptSegment(url, sequence, ivHex, segKeyUrl) {
-        const response = await chromeFetch(url, { signal: AbortSignal.timeout(SEGMENT_FETCH_TIMEOUT) });
+    async function fetchAndDecryptSegment(url, sequence, ivHex, segKeyUrl, abortSignal) {
+        // The caller's cancellation and this fetch's own timeout are composed, so the segment ends on whichever arrives first and a caller with nothing to cancel
+        // gets the timeout alone.
+        const timeout = AbortSignal.timeout(SEGMENT_FETCH_TIMEOUT);
+        const response = await chromeFetch(url, { signal: abortSignal ? AbortSignal.any([abortSignal, timeout]) : timeout });
         if (!response.ok) {
             LOG.debug("native:proxy", "Segment fetch failed for %s: HTTP %s.", channelName, response.status);
             return null;
@@ -736,7 +1140,9 @@ export function createNativeProxy(options) {
             // Look up the key in the per-URL cache, or fetch it if not cached.
             let key = keysByUrl.get(segKeyUrl);
             if (!key) {
-                key = await fetchDecryptionKey(segKeyUrl) ?? undefined;
+                // The key fetch receives the raw cancellation signal rather than the composed one above, so it gets its own full timeout budget instead of inheriting
+                // whatever this segment's fetch has already spent.
+                key = await fetchDecryptionKey(segKeyUrl, abortSignal) ?? undefined;
                 if (!key) {
                     LOG.debug("native:proxy", "Decryption key unavailable for %s (key URL: %s).", channelName, segKeyUrl.slice(0, 80));
                     return null;
@@ -744,16 +1150,33 @@ export function createNativeProxy(options) {
                 keysByUrl.set(segKeyUrl, key);
                 LOG.debug("native:proxy", "New decryption key cached for %s.", channelName);
             }
-            // Determine the IV: use explicit IV from the manifest, or derive from the media sequence number.
-            const iv = ivHex ? (parseExplicitIv(ivHex) ?? deriveIvFromSequence(sequence)) : deriveIvFromSequence(sequence);
-            LOG.debug("native:decrypt", "IV source for sequence %s: %s.", sequence, ivHex ? "explicit" : "sequence");
-            data = decryptSegment(data, key, iv);
+            // Determine the IV via the shared resolver. A malformed explicit IV is rejected rather than silently substituted with the sequence-derived IV, which would
+            // decrypt the segment with the wrong IV and serve plausible-looking but garbage video. Rejecting returns null here so the fetch tracker counts a failure and
+            // recovery can escalate.
+            const ivResult = resolveSegmentIv(ivHex, sequence);
+            if (ivResult.status === "reject") {
+                LOG.warn("Rejecting segment for %s: the manifest provided a malformed explicit IV.", channelName, { ivHex, sequence });
+                return null;
+            }
+            LOG.debug("native:decrypt", "IV source for sequence %s: %s.", sequence, (ivHex !== null) ? "explicit" : "sequence");
+            data = decryptSegment(data, key, ivResult.iv);
         }
         return data;
     }
     /**
-     * Fetches a segment with error tracking. Wraps fetchAndDecryptSegment with per-tracker failure counting. Consecutive failures trigger the error threshold which
-     * stops the proxy and signals the monitor for recovery. Used for both video and audio segments with independent trackers.
+     * Starts one segment's byte fetch for the prefetch scheduler, which applies accounting when the segment commits rather than when its bytes arrive. The
+     * proxy's cancellation signal is supplied here, so a fetch the scheduler started ahead of the commit walk ends the moment the proxy stops.
+     *
+     * @param segment - The parsed segment to fetch.
+     * @returns The segment data (decrypted if necessary), or null on failure.
+     */
+    async function prefetchSegment(segment) {
+        return fetchAndDecryptSegment(segment.url, segment.sequence, segment.ivHex, segment.keyUrl, lifecycle.abortController.signal);
+    }
+    /**
+     * Fetches a segment with error tracking, for the callers that fetch outside the pipeline's window: the initialization segments an fMP4 source's #EXT-X-MAP
+     * tags reference, which ride the track's own tracker so their failures escalate through the one segment threshold rather than a parallel counter. The fetch
+     * carries the proxy's cancellation signal and settles through the shared outcome classifier, so a cancelled initialization is discarded rather than counted.
      *
      * @param tracker - Mutable error tracking state with labels for log and error messages.
      * @param url - The segment URL.
@@ -763,38 +1186,17 @@ export function createNativeProxy(options) {
      * @returns The segment data (decrypted if necessary), or null on failure.
      */
     async function fetchTrackedSegment(tracker, url, sequence, ivHex, segKeyUrl) {
-        try {
-            const data = await fetchAndDecryptSegment(url, sequence, ivHex, segKeyUrl);
-            if (!data) {
-                tracker.consecutiveFailures++;
-                stats.totalFetchErrors++;
-                if (tracker.consecutiveFailures >= MAX_SEGMENT_FAILURES) {
-                    lifecycle.errorThresholdReached = true;
-                    lifecycle.stopped = true;
-                    onError(tracker.label + " fetch failed " + String(tracker.consecutiveFailures) + " times");
-                }
-                return null;
-            }
-            tracker.consecutiveFailures = 0;
-            return data;
-        }
-        catch (error) {
-            tracker.consecutiveFailures++;
-            stats.totalFetchErrors++;
-            LOG.debug("native:proxy", "%s fetch failed for %s: %s.", tracker.debugLabel, channelName, String(error));
-            if (tracker.consecutiveFailures >= MAX_SEGMENT_FAILURES) {
-                lifecycle.errorThresholdReached = true;
-                lifecycle.stopped = true;
-                onError(tracker.label + " fetch error: " + String(error));
-            }
-            return null;
-        }
+        const signal = lifecycle.abortController.signal;
+        const outcome = await captureFetchOutcome({ fetchSegment: () => fetchAndDecryptSegment(url, sequence, ivHex, segKeyUrl, signal), signal });
+        recordFetchOutcome({ ctx, outcome, tracker });
+        return (outcome.status === "success") ? outcome.data : null;
     }
     /**
      * Generates playlists from the stored segments. For streams without separate audio, generates a single variant playlist. When preroll is active (muxed audio only),
      * produces a composite playlist with fMP4 preroll entries and MPEG-TS real entries bridged by a DISCONTINUITY tag. The preroll entries use the same fMP4 segments
-     * served during the standalone preroll phase, ensuring smooth MEDIA-SEQUENCE progression. For streams with separate audio, generates a master playlist referencing
-     * video.m3u8 and audio.m3u8, plus individual variant playlists for each (no preroll - preroll is muxed and can't be split into separate renditions).
+     * served during the standalone preroll phase, ensuring smooth MEDIA-SEQUENCE progression. For streams with separate audio, generates the video variant playlist
+     * and the master playlist referencing video.m3u8 and audio.m3u8 (no preroll - preroll is muxed and can't be split into separate renditions); the audio variant
+     * playlist is produced separately by generateAudioPlaylist(), which the poll loop calls alongside this function.
      *
      * @param targetDuration - The #EXT-X-TARGETDURATION value from the service's manifest.
      */
@@ -852,6 +1254,9 @@ export function createNativeProxy(options) {
                 "video.m3u8\n";
             updatePlaylist(streamId, masterPlaylist);
         }
+        // Release initialization segments the freshly-generated window no longer references. This runs after generation so the retain set reflects exactly the
+        // segments the playlist just published.
+        pruneTrackInits(streamId, "video", video.metadata, segmentEntries);
         LOG.debug("native:proxy", "Playlist generated for %s with %s segment(s), target duration %ss.", channelName, segmentEntries.length, targetDuration);
     }
     /**
@@ -866,12 +1271,16 @@ export function createNativeProxy(options) {
         }
         const audioEntries = Array.from(stream.hls.audioSegments.keys());
         updateAudioPlaylist(streamId, buildVariantPlaylist(audioEntries, audio.metadata, "audio", targetDuration));
+        // Release initialization segments the freshly-generated audio window no longer references. The audio track's Map is pruned on its own, so this can never
+        // evict a video initialization.
+        pruneTrackInits(streamId, "audio", audio.metadata, audioEntries);
     }
     /**
      * Schedules the next manifest poll after a delay. The sleep is awaited through the injected Clock port (defaulting to realClock) so tests can virtualize the
      * polling cadence without depending on real timers. Cancellation semantics: stop() flips lifecycle.stopped, and the post-sleep guard catches that flip before
-     * issuing the next poll. The in-flight sleep itself is not cancelled - in production a stopped proxy lingers for at most one MANIFEST_BACKOFF_BASE before the
-     * awaiter wakes and exits cleanly. This is the same shape as retryOperation in utils/retry.ts which already adopted the Clock port for the same reason.
+     * issuing the next poll. The in-flight sleep itself is not cancelled - in production a stopped proxy lingers for at most the currently scheduled poll delay,
+     * which can be as long as MANIFEST_BACKOFF_CAP once jittered, before the awaiter wakes and exits cleanly. This is the same shape as retryOperation in
+     * utils/retry.ts which already adopted the Clock port for the same reason.
      *
      * @param delayMs - Delay in milliseconds before the next poll.
      */
@@ -887,11 +1296,37 @@ export function createNativeProxy(options) {
             void pollManifest();
         })();
     }
+    // The proxy's teardown: flip the lifecycle flag the polling awaiter checks, and cancel the pending token-refresh timer. Defined as a const so it can be exposed
+    // both as stop() (the established domain verb) and as [Symbol.dispose] (the TC39 protocol), making the proxy a self-disposing node without duplicating the body.
+    const stop = () => {
+        lifecycle.stopped = true;
+        // Cancel every fetch the proxy still has open - segments, initialization segments, and decryption keys - so teardown does not wait on a CDN and no
+        // straggler write can land after the stream's state has been cleared.
+        lifecycle.abortController.abort();
+        // The polling cadence sleep is owned by schedulePoll's awaiter and is not cancelled here - the awaiter checks lifecycle.stopped after clock.sleep resolves
+        // and exits before issuing the next poll. See schedulePoll's docblock for the cancellation contract.
+        // Cancel the pending token refresh timer to prevent fire-after-termination. Without this, the timer fires on a stopped proxy and attempts to navigate a
+        // potentially closed or reused page.
+        if (lifecycle.tokenRefreshTimer) {
+            clearTimeout(lifecycle.tokenRefreshTimer);
+            lifecycle.tokenRefreshTimer = null;
+        }
+        LOG.debug("native:proxy", "Stopped native proxy for %s.", channelName);
+    };
     return {
+        clearRefreshFailures: () => {
+            lifecycle.refreshFailureCount = 0;
+        },
         getConsecutiveErrors: () => video.segmentTracker.consecutiveFailures + video.consecutiveManifestFailures +
             audio.segmentTracker.consecutiveFailures + audio.consecutiveManifestFailures,
         getLastSegmentSize: () => video.lastSegmentSize,
         getLastSegmentTime: () => video.lastSegmentTime,
+        getPendingRefresh: () => lifecycle.pendingRefresh,
+        /* The envelope a refresh selects against, assembled from what construction fixed: the container the relay reads, the encryption kind it was built to handle,
+         * and whether its audio arrives as a separate rendition. It lives here because the pipeline lives here - the coordinator that runs the refresh holds a proxy
+         * reference and nothing else that could answer the question.
+         */
+        getPipelineShape: () => ({ container, encryption, separateAudio: hasAudio }),
         getSegmentIndex: () => video.segmentIndex,
         getStats: () => ({
             fetchErrors: stats.totalFetchErrors,
@@ -901,38 +1336,31 @@ export function createNativeProxy(options) {
         getTargetDuration: () => video.lastTargetDuration,
         hasErrored: () => lifecycle.errorThresholdReached,
         isStopped: () => lifecycle.stopped,
+        noteRefreshFailure: () => ++lifecycle.refreshFailureCount,
+        setPendingRefresh: (refresh) => {
+            lifecycle.pendingRefresh = refresh;
+        },
+        /* The proxy holds at most one live refresh timer, and this is the single site that writes the slot. Arming a successor therefore retires its predecessor
+         * here, so a reschedule cannot leave an orphaned handle firing against a proxy that a newer schedule already speaks for, and the stop path retires whichever
+         * handle is live when the stream ends.
+         */
         setTokenRefreshTimer: (timer) => {
+            if (lifecycle.tokenRefreshTimer) {
+                clearTimeout(lifecycle.tokenRefreshTimer);
+            }
             lifecycle.tokenRefreshTimer = timer;
         },
         start: () => {
             LOG.debug("native:proxy", "Starting native proxy for %s (%s).", channelName, encryption);
             void pollManifest();
         },
-        stop: () => {
-            lifecycle.stopped = true;
-            // The polling cadence sleep is owned by schedulePoll's awaiter and is not cancelled here - the awaiter checks lifecycle.stopped after clock.sleep resolves
-            // and exits before issuing the next poll. See schedulePoll's docblock for the cancellation contract.
-            // Cancel the pending token refresh timer to prevent fire-after-termination. Without this, the timer fires on a stopped proxy and attempts to navigate a
-            // potentially closed or reused page.
-            if (lifecycle.tokenRefreshTimer) {
-                clearTimeout(lifecycle.tokenRefreshTimer);
-                lifecycle.tokenRefreshTimer = null;
-            }
-            // Clean up the CDP session from manifest interception to prevent session leaks.
-            removeManifestInterceptor(activeCdpSession);
-            LOG.debug("native:proxy", "Stopped native proxy for %s.", channelName);
-        },
+        stop,
         updateAudioVariantUrl: (newUrl) => {
             audio.variantUrl = newUrl;
             audio.fetchedSequences.clear();
             audio.tokenRefreshPending = true;
             LOG.debug("native:proxy", "Audio variant URL updated for %s.", channelName);
         },
-        updateCdpSession: (session) => {
-            // Clean up the old CDP session before replacing it. This prevents session leaks when the session is swapped during token refresh or L2 recovery.
-            removeManifestInterceptor(activeCdpSession);
-            activeCdpSession = session;
-        },
         updateVariantUrl: (newUrl) => {
             video.variantUrl = newUrl;
             stats.totalTokenRefreshes++;
@@ -943,8 +1371,14 @@ export function createNativeProxy(options) {
             video.fetchedSequences.clear();
             video.lastMediaSequence = -1;
             video.tokenRefreshPending = true;
+            // Evict decryption keys the prior CDN session referenced but the live manifests no longer do. A token rotation typically retires the old session's key URL,
+            // so without this the per-URL key cache would grow by one dead entry per refresh over the stream's lifetime.
+            pruneStreamKeyCache();
             LOG.debug("native:proxy", "Variant URL updated for %s. Segment tracking reset.", channelName);
-        }
+        },
+        // TC39 explicit resource management hook aliasing stop(), so the proxy is a self-disposing node consumable via the protocol (a DisposableStack or "using"). The
+        // explicit teardown in disposeStreamResources calls stop() directly, following the codebase convention that explicit call sites use the readable verb.
+        [Symbol.dispose]: stop
     };
 }
 //# sourceMappingURL=proxy.js.map