refactor(spf): rename resolveCdnPriority to deriveCdnPriority

`resolve` is reserved for resolvables (presentations, tracks). This
behavior derives and owns the `cdnPriority` signal from the already-
resolved presentation, so `derive` is the accurate verb. Mirrors the
shape of `calculatePresentationDuration`.

Renames the behavior export, the `ResolveCdnPriorityState` type, the
module + test files, and all references across the HLS engines,
track-switching, and the multi-cdn-failover feature doc. The
`cdnPriority` signal/slot name is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cjpillsbury

internal/design/spf/features/multi-cdn-failover.md

@@ -41,7 +41,7 @@ ambiguity reflects that split.
 ## Status
 
 - **Composition:** both sub-features are implemented in
-  `createSimpleHlsEngine` and the audio-only engine. `resolveCdnPriority`
+  `createSimpleHlsEngine` and the audio-only engine. `deriveCdnPriority`
   owns the `cdnPriority` signal (manifest-ordered CDN list); the
   `preferActiveCdn` scope rule narrows candidates to the highest-priority CDN
   with surviving tracks (shared by the video + audio chains). For failover:
@@ -96,7 +96,7 @@ tracks, plus a fetch decorator that records failures into `failedCdns`.
 
 | Phase | Sub-feature | Kind | What | State |
 |---|---|---|---|---|
-| Sticky CDN pick | 1 | scope | `resolveCdnPriority` publishes the manifest-ordered CDN list (`cdnPriority`); `preferActiveCdn` narrows every type's candidates to the highest-priority CDN with surviving tracks, falling through when nothing matches. Shared list → all types on one CDN | **Implemented** |
+| Sticky CDN pick | 1 | scope | `deriveCdnPriority` publishes the manifest-ordered CDN list (`cdnPriority`); `preferActiveCdn` narrows every type's candidates to the highest-priority CDN with surviving tracks, falling through when nothing matches. Shared list → all types on one CDN | **Implemented** |
 | Constraints pre-pass | 2 | — | `applyConstraints` + the `constraints` config slot in `setupTrackSwitching` (the hard-filter pre-pass that runs before the rule chain). Reusable by capability-probing | **Implemented** |
 | Failed-CDN constraint | 2 | constraint | `excludeFailedCdns` prunes tracks whose CDN ∈ `failedCdns`; the scope falls to the next `cdnPriority` entry and snaps back on recovery | **Implemented** |
 | Per-CDN failure tracking | 2 | — | **Site-adds, behavior-expires**: fetch sites trip a CDN into `failedCdns` on a failed fetch (`failoverFetch` / `failoverFetchBytes`); `setupFailoverMonitor` expires it after a cooldown. Self-contained (trip-on-first-failure + cooldown), not a `network-resilience` circuit-breaker | **Implemented** |
@@ -139,7 +139,7 @@ tracks, plus a fetch decorator that records failures into `failedCdns`.
   video and audio chains reference the *same* `preferActiveCdn` definition
   reading the *same* list, so they agree on the CDN even if their per-type
   track arrays differ. (The doc's earlier per-rendition lean is superseded.)
-- **`cdnPriority` writer composition.** `resolveCdnPriority` is the sole
+- **`cdnPriority` writer composition.** `deriveCdnPriority` is the sole
   writer today (publishes the manifest order). Failover needs no second
   writer — the failed-CDN constraint prunes tracks and the scope re-derives
   the active CDN. Content-steering would *reorder* `cdnPriority` (still a
@@ -157,7 +157,7 @@ tracks, plus a fetch decorator that records failures into `failedCdns`.
   terminal "everything pruned" state — today an all-CDNs-failed candidate set
   is empty and the prior pick is left in place (see *Follow-up candidates*).
 - **Live + multi-CDN.** During live playback the reload loop re-resolves
-  the presentation; `resolveCdnPriority` re-publishes only when the CDN set
+  the presentation; `deriveCdnPriority` re-publishes only when the CDN set
   changes (idempotent for a stable manifest). Cross-feature with
   [live-stream-support](./live-stream-support.md) (not yet implemented).
 - **Failover state is per-source.** Both `cdnPriority` and `failedCdns` tear
@@ -224,7 +224,7 @@ tracking as a future effort:
 - **`media/utils/cdn.ts`** — `getCdnId(url)` (origin-based default) + the
   `GetCdnId` type; `getOrderedCdnIds(presentation, getCdnId?)`;
   `addFailedCdn(failed, cdn)` (pure, idempotent dedup-append).
-- **`playback/behaviors/resolve-cdn-priority.ts`** — `resolveCdnPriority` owns
+- **`playback/behaviors/derive-cdn-priority.ts`** — `deriveCdnPriority` owns
   `cdnPriority` (publishes `getOrderedCdnIds` on resolve, skips unchanged
   writes, clears on exit).
 - **`playback/behaviors/setup-failover-monitor.ts`** — `setupFailoverMonitor`
@@ -240,13 +240,13 @@ tracking as a future effort:
   `CdnRuleConfig` view that carries `getCdnId`); `applyConstraints` pre-pass +
   `constraints` config slot; `SwitchableTrack` gains `url`.
 - **`playback/engines/hls/engine.ts` + `engine-audio-only.ts`** —
-  `resolveCdnPriority` + `setupFailoverMonitor` composed after
+  `deriveCdnPriority` + `setupFailoverMonitor` composed after
   `resolvePresentation`; `failover?` + `getCdnId?` engine config; `cdnPriority?`
   + `failedCdns?` engine state.
 - **`network/fetch.ts`** — `FetchText` type + `fetchResolvableText` default
   (fetch → reject on non-OK → text), the text analog of `FetchBytes`.
 
-State signals: `cdnPriority?: string[]` (owned by `resolveCdnPriority`) and
+State signals: `cdnPriority?: string[]` (owned by `deriveCdnPriority`) and
 `failedCdns?: string[]` (owned by `setupFailoverMonitor`; tripped by the fetch
 sites, read by the `excludeFailedCdns` constraint).
 
@@ -255,7 +255,7 @@ sites, read by the `excludeFailedCdns` constraint).
 - `media/utils/tests/cdn.test.ts` — `getCdnId` (origin; same/different host;
   scheme+port; unparseable fallback); `getOrderedCdnIds` (order; dedupe; single;
   unresolved → `[]`); `addFailedCdn` (append; order; idempotent same-reference).
-- `playback/behaviors/tests/resolve-cdn-priority.test.ts` — publishes the
+- `playback/behaviors/tests/derive-cdn-priority.test.ts` — publishes the
   manifest-ordered list; single-CDN; skips the write on a same-CDN swap; updates
   on reorder; clears on unload/destroy; re-publishes after reset.
 - `playback/behaviors/tests/setup-failover-monitor.test.ts` — a tripped CDN is

…ayback/behaviors/resolve-cdn-priority.ts …layback/behaviors/derive-cdn-priority.tspackages/spf/src/playback/behaviors/resolve-cdn-priority.ts renamed to packages/spf/src/playback/behaviors/derive-cdn-priority.ts packages/spf/src/playback/behaviors/resolve-cdn-priority.ts renamed to packages/spf/src/playback/behaviors/derive-cdn-priority.ts

@@ -31,7 +31,7 @@ import { computed, peek, type ReadonlySignal, type Signal } from '../../core/sig
 import { isResolvedPresentation, type MaybeResolvedPresentation } from '../../media/types';
 import { getCdnId as defaultGetCdnId, type GetCdnId, getOrderedCdnIds } from '../../media/utils/cdn';
 
-export interface ResolveCdnPriorityState {
+export interface DeriveCdnPriorityState {
   presentation?: MaybeResolvedPresentation;
   cdnPriority?: string[];
 }
@@ -44,18 +44,18 @@ const samePriority = (a: string[] | undefined, b: string[]): boolean =>
  * on src unload.
  *
  * @example
- * const reactor = resolveCdnPriority.setup({ state });
+ * const reactor = deriveCdnPriority.setup({ state });
  */
-export const resolveCdnPriority = defineBehavior({
+export const deriveCdnPriority = defineBehavior({
   stateKeys: ['presentation', 'cdnPriority'],
   contextKeys: [],
   setup: ({
     state,
     config = {},
   }: {
     state: {
-      presentation: ReadonlySignal<ResolveCdnPriorityState['presentation']>;
-      cdnPriority: Signal<ResolveCdnPriorityState['cdnPriority']>;
+      presentation: ReadonlySignal<DeriveCdnPriorityState['presentation']>;
+      cdnPriority: Signal<DeriveCdnPriorityState['cdnPriority']>;
     };
     config?: { getCdnId?: GetCdnId };
   }) => {

…viors/tests/resolve-cdn-priority.test.ts …aviors/tests/derive-cdn-priority.test.tspackages/spf/src/playback/behaviors/tests/resolve-cdn-priority.test.ts renamed to packages/spf/src/playback/behaviors/tests/derive-cdn-priority.test.ts packages/spf/src/playback/behaviors/tests/resolve-cdn-priority.test.ts renamed to packages/spf/src/playback/behaviors/tests/derive-cdn-priority.test.ts

@@ -2,9 +2,9 @@ import { describe, expect, it } from 'vitest';
 import type { StateSignals } from '../../../core/composition/create-composition';
 import { signal } from '../../../core/signals/primitives';
 import type { MaybeResolvedPresentation, PartiallyResolvedVideoTrack, Presentation } from '../../../media/types';
-import { type ResolveCdnPriorityState, resolveCdnPriority } from '../resolve-cdn-priority';
+import { type DeriveCdnPriorityState, deriveCdnPriority } from '../derive-cdn-priority';
 
-function makeState(initial: Partial<ResolveCdnPriorityState> = {}): StateSignals<ResolveCdnPriorityState> {
+function makeState(initial: Partial<DeriveCdnPriorityState> = {}): StateSignals<DeriveCdnPriorityState> {
   return {
     presentation: signal<MaybeResolvedPresentation | undefined>(initial.presentation),
     cdnPriority: signal<string[] | undefined>(initial.cdnPriority),
@@ -50,34 +50,34 @@ const redundant = (id = 'pres-1'): Presentation =>
 
 const flush = () => Promise.resolve().then(() => Promise.resolve());
 
-describe('resolveCdnPriority', () => {
+describe('deriveCdnPriority', () => {
   it('does nothing without a presentation', async () => {
     const state = makeState();
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toBeUndefined();
     reactor.destroy();
   });
 
   it('publishes the manifest-ordered CDN list on src load', async () => {
     const state = makeState({ presentation: redundant() });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toEqual(['https://cdn-a.example.com', 'https://cdn-b.example.com']);
     reactor.destroy();
   });
 
   it('publishes a single-entry list for a non-redundant source', async () => {
     const state = makeState({ presentation: presentationWith(['https://cdn-a.example.com/720p.m3u8']) });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toEqual(['https://cdn-a.example.com']);
     reactor.destroy();
   });
 
   it('does not re-set the list when a resolved swap keeps the same CDNs', async () => {
     const state = makeState({ presentation: redundant() });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     const first = state.cdnPriority.get();
 
@@ -92,7 +92,7 @@ describe('resolveCdnPriority', () => {
 
   it('updates the list when a resolved swap changes the CDN order', async () => {
     const state = makeState({ presentation: redundant() });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toEqual(['https://cdn-a.example.com', 'https://cdn-b.example.com']);
 
@@ -107,7 +107,7 @@ describe('resolveCdnPriority', () => {
 
   it('clears cdnPriority on src unload', async () => {
     const state = makeState({ presentation: redundant() });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toBeDefined();
 
@@ -120,7 +120,7 @@ describe('resolveCdnPriority', () => {
 
   it('clears cdnPriority on destroy', async () => {
     const state = makeState({ presentation: redundant() });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toBeDefined();
 
@@ -130,7 +130,7 @@ describe('resolveCdnPriority', () => {
 
   it('re-publishes after a src reset (undefined → new resolved)', async () => {
     const state = makeState({ presentation: redundant() });
-    const reactor = resolveCdnPriority.setup({ state });
+    const reactor = deriveCdnPriority.setup({ state });
     await flush();
     expect(state.cdnPriority.get()).toEqual(['https://cdn-a.example.com', 'https://cdn-b.example.com']);
 

packages/spf/src/playback/behaviors/tests/track-switching.test.ts

@@ -851,8 +851,8 @@ describe('preferActiveCdn (active-CDN scope)', () => {
   });
 
   it('applies the scope when cdnPriority arrives after the first pick (composition-order independence)', async () => {
-    // Guards against the pick depending on `resolveCdnPriority` being composed
-    // *before* `switchVideoTrack`. The worst case — resolveCdnPriority last — is
+    // Guards against the pick depending on `deriveCdnPriority` being composed
+    // *before* `switchVideoTrack`. The worst case — deriveCdnPriority last — is
     // equivalent to cdnPriority being written after switch*'s first pick. The
     // scope subscribes to cdnPriority even while it's undefined, so a late write
     // must re-fire and correct the pick.

packages/spf/src/playback/behaviors/track-switching.ts

@@ -17,7 +17,7 @@
  *   2. **active CDN** — a soft filter on `cdnPriority` (`preferActiveCdn`):
  *      narrow to the highest-priority CDN that still has tracks; an empty match
  *      falls through. Shared by video and audio, so every type stays on one CDN
- *      (`resolveCdnPriority` owns the list). No-op for non-redundant sources.
+ *      (`deriveCdnPriority` owns the list). No-op for non-redundant sources.
  *   3. **ranking** — the terminal sort: `rankByBandwidth`, shared by video and
  *      audio. Fitting tracks (within the throughput threshold) first, highest
  *      bitrate first; over-throughput tracks after, least-over first. Hysteresis
@@ -310,7 +310,7 @@ type BandwidthRankerConfig<S extends SelectionKey, T extends SwitchableTrack> =
 /**
  * State the active-CDN scope reads: the lifecycle map plus an *optional*
  * `cdnPriority` — the manifest-ordered CDN list (most-preferred first). The
- * signal exists only when the composition includes `resolveCdnPriority` (which
+ * signal exists only when the composition includes `deriveCdnPriority` (which
  * materializes + owns it); the scope reads it defensively and passes through
  * when it's absent (no CDN preference).
  */
@@ -331,7 +331,7 @@ type CdnConstraintStateMap<S extends SelectionKey> = TrackSwitchingStateMap<S> &
 /**
  * Config the CDN rules read: the base config plus an *optional* `getCdnId`
  * override. Both `excludeFailedCdns` and `preferActiveCdn` derive a track's CDN
- * from its URL; the override must be the *same* one `resolveCdnPriority` and the
+ * from its URL; the override must be the *same* one `deriveCdnPriority` and the
  * failover trip use, or the keys stop matching. Optional → defaults to the
  * origin-based `getCdnId`, so the base config (without it) stays assignable.
  */
@@ -389,7 +389,7 @@ function excludeFailedCdns<S extends SelectionKey, T extends SwitchableTrack>(
 
 /**
  * Active-CDN scope — a soft filter, shared by video and audio. Narrows to the
- * highest-priority CDN in `cdnPriority` (owned by `resolveCdnPriority`) that
+ * highest-priority CDN in `cdnPriority` (owned by `deriveCdnPriority`) that
  * still has tracks, so every track type stays on one CDN. A redundant-streams
  * source lists the same renditions on multiple hosts; this keeps the pick on one
  * host rather than letting the ranker drift across them.
@@ -405,7 +405,7 @@ function excludeFailedCdns<S extends SelectionKey, T extends SwitchableTrack>(
  * Non-redundant sources have one CDN, so the narrow is a no-op.
  *
  * The CDN-id derivation defaults to origin-based `getCdnId`, overridable via the
- * `getCdnId` config — it must match the one `resolveCdnPriority` used to build
+ * `getCdnId` config — it must match the one `deriveCdnPriority` used to build
  * `cdnPriority`, or no track's CDN would ever equal an entry.
  */
 function preferActiveCdn<S extends SelectionKey, T extends SwitchableTrack>(

packages/spf/src/playback/engines/hls/engine-audio-only.ts

@@ -17,14 +17,14 @@ import {
   calculatePresentationDuration,
   type PresentationDurationResolver,
 } from '../../behaviors/calculate-presentation-duration';
+import { deriveCdnPriority } from '../../behaviors/derive-cdn-priority';
 import { endOfStream } from '../../behaviors/dom/end-of-stream';
 import { loadAudioSegments } from '../../behaviors/dom/load-segments';
 import { setupAudioBufferActors } from '../../behaviors/dom/setup-buffer-actors';
 import { setupMediaSource } from '../../behaviors/dom/setup-mediasource';
 import { trackCurrentTime } from '../../behaviors/dom/track-current-time';
 import { trackLoadTriggers } from '../../behaviors/dom/track-load-triggers';
 import { updateMediaSourceDuration } from '../../behaviors/dom/update-mediasource-duration';
-import { resolveCdnPriority } from '../../behaviors/resolve-cdn-priority';
 import { type ParsePresentation, resolvePresentation } from '../../behaviors/resolve-presentation';
 import { resolveAudioTrack } from '../../behaviors/resolve-track';
 import { type FailoverMonitorConfig, setupFailoverMonitor } from '../../behaviors/setup-failover-monitor';
@@ -56,7 +56,7 @@ export interface SimpleHlsAudioOnlyEngineState {
   userAudioTrackSelection?: Partial<AudioTrack>;
   /**
    * The CDNs the source is served from, in manifest priority order (mirrors
-   * HLS content steering's `PATHWAY-PRIORITY`). Owned by `resolveCdnPriority`,
+   * HLS content steering's `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`,
    * read by `track-switching`'s `preferActiveCdn` scope. Only meaningful for
    * redundant-stream sources; a single-CDN source has one entry.
    */
@@ -178,7 +178,7 @@ export function createHlsAudioOnlyEngine(
       // not load-bearing here today. It earns its place for forward-consistency
       // with the default engine and for future failover / steering, where the
       // active CDN changes dynamically (and selection stays reactive either way).
-      resolveCdnPriority,
+      deriveCdnPriority,
 
       // CDN failover cooldown: watches `failedCdns` (tripped directly by audio
       // track resolution on a failed media-playlist fetch) and removes each CDN

packages/spf/src/playback/engines/hls/engine.ts

@@ -27,6 +27,7 @@ import {
   calculatePresentationDuration,
   type PresentationDurationResolver,
 } from '../../behaviors/calculate-presentation-duration';
+import { deriveCdnPriority } from '../../behaviors/derive-cdn-priority';
 import { endOfStream } from '../../behaviors/dom/end-of-stream';
 import { loadAudioSegments, loadTextTrackSegments, loadVideoSegments } from '../../behaviors/dom/load-segments';
 import { setupAudioBufferActors, setupVideoBufferActors } from '../../behaviors/dom/setup-buffer-actors';
@@ -36,7 +37,6 @@ import { syncTextTracks } from '../../behaviors/dom/sync-text-tracks';
 import { trackCurrentTime } from '../../behaviors/dom/track-current-time';
 import { trackLoadTriggers } from '../../behaviors/dom/track-load-triggers';
 import { updateMediaSourceDuration } from '../../behaviors/dom/update-mediasource-duration';
-import { resolveCdnPriority } from '../../behaviors/resolve-cdn-priority';
 import { type ParsePresentation, resolvePresentation } from '../../behaviors/resolve-presentation';
 import { resolveAudioTrack, resolveTextTrack, resolveVideoTrack } from '../../behaviors/resolve-track';
 import { selectTextTrack } from '../../behaviors/select-tracks';
@@ -77,7 +77,7 @@ export interface SimpleHlsEngineState {
   /**
    * The CDNs the source is served from (track-URL origins), in manifest
    * priority order — most-preferred first (mirrors HLS content steering's
-   * `PATHWAY-PRIORITY`). Owned by `resolveCdnPriority`, read by
+   * `PATHWAY-PRIORITY`). Owned by `deriveCdnPriority`, read by
    * `track-switching`'s `preferActiveCdn` scope, which narrows to the
    * highest-priority CDN with surviving tracks so video / audio / text stay on
    * one host. Only meaningful for redundant-stream sources; a single-CDN source
@@ -300,7 +300,7 @@ export function createSimpleHlsEngine(
       // media-playlist fetch to the wrong CDN before correcting. Symmetric
       // redundant streams (the norm) never hit it — the first-listed CDN is
       // already the primary we'd pick anyway.
-      resolveCdnPriority,
+      deriveCdnPriority,
 
       // CDN failover cooldown: owns the expiry half of failover — watches
       // `failedCdns` (tripped directly by track resolution on a failed