Host control over clampLiveResumeIfBehindWindow: the in-play() snap preempts host resume policy, and its DVR clamp aims at the arithmetic lower bound

[cmcpherson274]

What should the engine do?

Let the host own the resume policy for a behind-live session: an option to disable
clampLiveResumeIfBehindWindow()'s automatic snap, which today runs inside play() and
silently moves the playhead (AetherEngine+Live.swift:50-65, unchanged 6.21.0 →
cb3baaf):

• live-only (no DVR window): behindLiveSeconds > 45 → seekToLiveEdge();
• DVR window: behind beyond the window → seek to seekableLiveRange.lowerBound + 5.

Two problems for a host with its own live-pause semantics:

1. The snap preempts the host's resume policy. Ours decides at resume time whether a
   long-paused live session re-tunes fresh or stays parked behind live (a ≥90 s pause
   has its own product-defined path); the engine's silent seek inside play() makes
   that decision first and invisibly. A viewer who paused live TV for a minute and a
   half resumes somewhere they didn't choose.
2. When the DVR-window clamp IS warranted, it aims at seekableLiveRange.lowerBound + 5
   — which is window arithmetic, not the cache's real floor (seekableLiveRange's lower bound is window arithmetic (max(0, edge − window)) — it never consults the cache, so the advertised rewind depth over-promises #441) —
   so the clamp target can be a position that was never retained.

The ask: a LoadOptions (or transport) flag — host-owned resume, no implicit seek in
play(); the engine reports (it already publishes behindLiveSeconds) and the host
decides. Default can stay exactly today's behavior. And when clamping remains enabled,
clamp against the real resident floor once one exists.

Motivating media or use case

Live TV with pause/rewind in a tvOS Jellyfin client (raw-TS via Jellyfin 10.11, native
loopback route, dvrWindowSeconds: 1800). The host carries measured, product-approved
pause semantics (latched long-pause re-tune vs in-place resume); the engine's in-play()
snap makes those unreachable on this rung. Measured sessions: stable −540 s behind-live
playback demonstrates the "deliberately far behind" state is real and healthy — a resume
there must not teleport.

Area

Public API surface

Host app / integration context

Custom tvOS Jellyfin client; behavior verified in source at 6.21.0 (87868c1) and 6.50.1
(cb3baaf); measurement harness aetherctl on macOS 26.5.2 / M4 Max.

Would you be willing to open a PR?

Maybe, with guidance

[superuser404notfound]

Both halves are on fix/ae441-resident-live-floor.

The clamp target is answered by the commit before this one (906ee421, #441):
clampLiveResumeIfBehindWindow() lands on seekableLiveRange.lowerBound, and that bound is now the
intersection of the window and the cache's real resident floor, so it can no longer aim at a position that
was never retained.

The policy is LoadOptions.clampsLiveResumeToWindow (8df76d4e), defaulting to true, exactly
today's behaviour. Set false and play() moves nothing: the engine keeps publishing
behindLiveSeconds, seekableLiveRange and isAtLiveEdge, and seekToLiveEdge() performs the same
recovery when asked. The documentation says out loud what the host takes on with it, namely that nothing
then rescues a playhead the window has evicted.

Two notes on the reasoning, since the ask framed the snap as policy.

It is a recovery, not an opinion about where a viewer should be. Both branches only fire for a position
that no longer exists: a live-only source retains seconds, so a playhead 45 s back is gone, and the DVR
branch requires behindLiveSeconds > window - 5, i.e. the window has slid past the playhead. The measured
healthy state in the report, 540 s behind inside an 1800 s window, was never touched by it and is pinned
by a test now. What the ask is really about is that a RECOVERY and a PRODUCT DECISION were competing for
the same moment, and the recovery ran first because it lives inside play(). That is a fair complaint and
it is what the option fixes.

A resume that deliberately does not move now logs that it deferred. Silence there is indistinguishable
from a resume that was never behind, and an option whose whole purpose is that somebody else decides
should not be invisible in a log.

The two inline branches are one pure liveResumeAction now, so the whole policy is greppable and
testable without a live source, and the 45 s threshold and the 5 s landing margin are named rather than
literals in the middle of it.

[superuser404notfound]

Released in 6.52.0 as LoadOptions.clampsLiveResumeToWindow, default true so nothing changes without opting in. The clamp target half came with #441 in the same release.