Catch-up P1: resolve persisted M3U archive metadata into playback timeline

[MrFr3di]

Parent: #184
Follows: #277 / PR #280

Objective

Implement Slice E for M3U provider catch-up only: consume the catch-up metadata MuxTV already parses and persists, normalize the supported M3U dialect into the provider-neutral PlaybackIntent / ResolvedPlaybackTimeline contract, and keep provider URL/template semantics out of Media3 and presentation.

Confirmed current gap

The data already exists end-to-end through ingest/import/persistence:

StreamingM3uParser -> CatalogImportEntry -> ProviderChannelEntity

with:

• catchupMode;
• catchupSource;
• catchupDays;
• catchupCorrection.

No Room migration is required.

The current PlaybackCatalogDao/RoomPlaybackCatalog access projection does not carry these fields into archive resolution, so the metadata is persisted but cannot currently drive provider-neutral catch-up playback semantics.

Evidence-backed first dialect

Use the repository-owned sanitized corpus before adding production behavior. Current fixture:

catalog/ingest/src/test/resources/compatibility/m3u/catchup/catchup-metadata.m3u

locks an M3U form using:

• catchup="append";
• catchup-source="?utc={utc}...";
• catchup-days="7";
• catchup-correction="+2.0".

Do not add guessed catch-up dialects/templates without a compatibility fixture first.

Ownership / architecture

• provider/dialect normalization belongs beside existing provider resolution in catalog:refresh (current precedent: XtreamPlaybackReferenceResolver);
• player:api remains provider-neutral and owns PlaybackIntent / ResolvedPlaybackTimeline;
• catalog:api and player:api must not gain a dependency cycle;
• player:media3 must not parse M3U/Kodi templates;
• Guide/Compose must not construct provider URLs;
• active seek mutation remains solely under Playback: measured seek/rebuffer, back-buffer and optional cache residuals after single service-owned seek authority #132;
• live playback behavior must remain unchanged.

TDD sequence

1. RED JVM contract test first for the repository-owned append + {utc} fixture semantics.
2. Minimal provider-specific normalizer/resolver only.
3. Deterministic UTC retention/correction math with typed unavailable outcomes for requests outside retention.
4. Carry only the minimum safe persisted metadata needed to the resolution boundary; no raw secret-bearing generated URL in diagnostics/toString.
5. Keep transport materialization inside the existing provider/catalog access path.
6. Exact-head host validation before merge; no new Android AVD.

Acceptance

• PlaybackIntent.Live cannot accidentally select an archive template;
• supported M3U catch-up programme/position intents resolve deterministically from explicit UTC epoch values;
• retention window derives from persisted catchupDays and cannot be escaped by rounding/correction;
• correction parsing/math is deterministic and bounded;
• unsupported/malformed mode/template returns typed secret-free unavailable result;
• no locator/query/token/Cookie/Authorization value enters logs, UI semantics or public diagnostics;
• no Room schema change;
• no second player/seek/retry owner;
• existing Live playback remains behavior-identical.

Non-goals

Xtream catch-up, Guide launch UI, local timeshift, DVR, VOD/Series, Media3 mechanics, buffer tuning, new provider framework, new Gradle infrastructure module, third persistent AVD.

[MrFr3di]

Evidence checkpoint before RED implementation:

• repository corpus fixture compatibility/m3u/catchup/catchup-metadata.m3u uses catchup="append", catchup-source="?utc={utc}...", catchup-days="7", catchup-correction="+2.0";
• Kodi PVR IPTV Simple documents append as appending catchup-source to the channel URL;
• {utc} is the programme start time in UTC epoch-seconds;
• catchup-correction is an hour-valued correction used for catch-up URL generation, with documented range -12h..+14h.

Prepared RED-only branch catchup/285-m3u-timeline-resolver at f57eb7ef2f83a780370b43140f7e485a8c1cb86c, parented by PR #280 exact head. It adds only a player:api test dependency plus M3uCatchupResolverContractTest; no production resolver exists yet. The PR is intentionally not opened against the stacked non-main base because Hosted validation is configured only for pull_request.branches: [main]. After #280 lands, open this branch directly against main, observe the expected compile RED, then implement the minimum GREEN.

[MrFr3di]

Implementation checkpoint (2026-09-01):

• feat(catchup): normalize M3U archive timeline #288 merged as main@44a5b659a72d98c6b90a3fbbb63ed0ab43b7191c: evidence-backed M3U append + {utc} timeline normalization, retention, bounded correction and secret-safe typed outcomes.
• transport-materialization RED is retained at 820576d622616d1a78e0996919ccb38fb4970421 / backup/catchup-285-transport-red-20260901; Hosted validation #2024 failed specifically because M3uCatchupTransportResolver / M3uCatchupTransportResolution were absent.
• current GREEN candidate is PR feat(catchup): materialize M3U archive transport #291, exact head d7dc917e561300533c0ecb3bdd1c5afbcb13babb, based directly on accepted main@44a5b659..., exactly two changed files and zero behind. It materializes corrected/rounded {utc}, revalidates the materialized instant against retention, literally appends the persisted source suffix, and redacts the ephemeral locator from diagnostics. Fresh Hosted validation #2026 is running on that exact head.

Remaining Slice E work after #291 qualifies/lands: project only the minimum persisted ProviderChannelEntity.catchupMode/source/days/correction fields through the active-variant access boundary and invoke provider-owned catch-up resolution inside the existing catalog/access pipeline. No Room schema change, no change to current Live resolveVariant(), no Guide/Media3 URL construction, and no new provider framework.