v10/internal/design/spf/features/source-replacement.md

status, date, definition

status	date	definition
implemented	2026-05-20	sketched

Source replacement

An attached engine can resolve and play another source without being recreated.

Implemented decisions

• Replacing the unresolved presentation drives the existing resolution machine through a new source lifecycle.
• Every behavior gated by a resolved presentation must fully release its per-source state on state exit. This cleanup contract is load-bearing.
• Abort asynchronous source work and destroy per-source actors before the next source becomes active.
• Reset source-specific slots while retaining intentionally engine-wide knowledge such as the bandwidth estimate.
• Verify replacement through composition tests, not only isolated behavior tests, because failures usually appear across ownership boundaries.

Deferred scope

Cross-codec transitions, surfaced source-resolution errors, optional estimator reset, and concurrent prefetch are independent features.

Current sources of truth

• Presentation resolution and tests: packages/spf/src/playback/behaviors/resolve-presentation.ts and its colocated tests
• Lifecycle cleanup across behaviors: packages/spf/src/playback/behaviors/
• End-to-end engine composition tests: packages/spf/src/playback/engines/hls/tests/