feat(380): extract shuffle-source construction to ShuffleSourceBuilder (kill PlaylistEnumerator's cross-engine reach-in) #391

Merged
timothy merged 4 commits from feat/380-enumerator-seam into main 2026-07-17 09:05:15 +02:00
Owner

Fixes #380.

What

Extracts the two shuffle-source helpers (GetGroupedMediaItemsForShuffle, GetCollectionItemsForShuffleInOrder) out of PlayoutBuilder into a new public static class ShuffleSourceBuilder (ErsatzTV.Core/Scheduling). This eliminates the scheduler's one cross-engine reach-in: PlaylistEnumerator was calling those two PlayoutBuilder statics directly (one engine reaching into another engine's class). Classic and Playlist now share one directly-unit-tested place to build shuffle sources.

Scope: (a)-only by design

Per the frontier design pass recorded on #380 and in docs/decisions.md (2026-07-17):

  • Shipped (a): move the statics + kill the reach-in. Kept as a static helper (deps as params, not DI) to match the sibling MultiCollectionGrouper/MultiPartEpisodeGrouper and because PlaylistEnumerator.Create is itself a static factory.
  • Rejected (b): a unified Classic+Playlist enumerator factory — that would be the god-factory #380 forbids (Marathon→PlaylistEnumerator dependency cycle; Playlist's hardcoded flags vs Classic's schedule-flag reads = silent behavior change; asymmetric CustomOrder/Rerun/template arms). Engine separation preserved.
  • Left alone: Block (distinct PlayoutHistory family); the Scripted≡YAML construction duplication → separate follow-up gated on #381 (no golden coverage there yet).

One intentional signature change

GetGroupedMediaItemsForShuffle now takes bool keepMultiPartEpisodesTogether, bool treatCollectionsAsShows instead of a ProgramSchedule (verified those are the only two properties it read). This deletes PlaylistEnumerator's fake new ProgramSchedule { KeepMultiPartEpisodesTogether = false } (its TODO becomes an honest false, false) and gives future callers without a ProgramSchedule (#176 PseudoTV, #70 distribution) a schedule-entity-free entry point. Behavior unchanged.

Why the net had to be extended first (commit 1)

The #163 golden net only pinned PlaybackOrder.Chronological (Classic + Block). The paths this PR moves — the two statics and the Playlist reach-in — had zero coverage, so "goldens green" would have been a false signal. Commit 1 adds, before any production change:

  • PlayoutBuildGoldenTests.Classic_shuffle — Classic builder + PlaybackOrder.Shuffle, pinned Playout.Seed via Continue mode (Reset randomizes the seed) → deterministic + TZ-independent.
  • PlaylistEnumeratorTests.ReachIn_Shuffle_And_ShuffleInOrder_Items_Are_Characterized — a playlist with a Shuffle item and a ShuffleInOrder item, pinned seed, asserting the emitted id sequence (covers both reach-in call sites).

Commit 2 then does the behavior-preserving move and adds direct ShuffleSourceBuilderTests for the branches goldens don't reach (multi-collection vs fake-multi-collection lookup; multi-part grouping on/off).

Verification

  • Characterization goldens byte-identical before/after the move; reach-in sequence unchanged.
  • Full ErsatzTV.Core.Tests: 546 passed, 1 skipped, 0 failed (TZ=UTC).
  • grep confirms no external callers of the old PlayoutBuilder.Get* statics remain.
  • PlayoutBuilder.cs de-BOM'd + whitespace-normalized per fix-as-you-touch (#311).

Docs

docs/decisions.md entry added (Index + append). Scheduling map unchanged (same engines/enumerators), so domain-model.md/contributing.md need no update.

Independent adversarial review + Review-verdict: to follow. Live-E2E deliberately skipped: pure internal refactor, no /api/* endpoint or handler changed, and the playout-build path is exercised end-to-end by the golden tests against a real SQLite DB.

Fixes #380. ## What Extracts the two shuffle-source helpers (`GetGroupedMediaItemsForShuffle`, `GetCollectionItemsForShuffleInOrder`) out of `PlayoutBuilder` into a new `public static class ShuffleSourceBuilder` (`ErsatzTV.Core/Scheduling`). This eliminates the scheduler's **one** cross-engine reach-in: `PlaylistEnumerator` was calling those two `PlayoutBuilder` statics directly (one engine reaching into another engine's class). Classic and Playlist now share one directly-unit-tested place to build shuffle sources. ## Scope: (a)-only by design Per the frontier design pass recorded on #380 and in `docs/decisions.md` (2026-07-17): - **Shipped (a):** move the statics + kill the reach-in. Kept as a static helper (deps as params, not DI) to match the sibling `MultiCollectionGrouper`/`MultiPartEpisodeGrouper` and because `PlaylistEnumerator.Create` is itself a static factory. - **Rejected (b):** a unified Classic+Playlist enumerator factory — that would be the god-factory #380 forbids (Marathon→PlaylistEnumerator dependency cycle; Playlist's hardcoded flags vs Classic's schedule-flag reads = silent behavior change; asymmetric CustomOrder/Rerun/template arms). Engine separation preserved. - **Left alone:** Block (distinct `PlayoutHistory` family); the Scripted≡YAML construction duplication → separate follow-up gated on #381 (no golden coverage there yet). ## One intentional signature change `GetGroupedMediaItemsForShuffle` now takes `bool keepMultiPartEpisodesTogether, bool treatCollectionsAsShows` instead of a `ProgramSchedule` (verified those are the only two properties it read). This deletes `PlaylistEnumerator`'s fake `new ProgramSchedule { KeepMultiPartEpisodesTogether = false }` (its TODO becomes an honest `false, false`) and gives future callers without a `ProgramSchedule` (#176 PseudoTV, #70 distribution) a schedule-entity-free entry point. Behavior unchanged. ## Why the net had to be extended first (commit 1) The #163 golden net only pinned `PlaybackOrder.Chronological` (Classic + Block). The paths this PR moves — the two statics and the Playlist reach-in — had **zero** coverage, so "goldens green" would have been a false signal. Commit 1 adds, **before** any production change: - `PlayoutBuildGoldenTests.Classic_shuffle` — Classic builder + `PlaybackOrder.Shuffle`, pinned `Playout.Seed` via `Continue` mode (Reset randomizes the seed) → deterministic + TZ-independent. - `PlaylistEnumeratorTests.ReachIn_Shuffle_And_ShuffleInOrder_Items_Are_Characterized` — a playlist with a Shuffle item and a ShuffleInOrder item, pinned seed, asserting the emitted id sequence (covers both reach-in call sites). Commit 2 then does the behavior-preserving move and adds direct `ShuffleSourceBuilderTests` for the branches goldens don't reach (multi-collection vs fake-multi-collection lookup; multi-part grouping on/off). ## Verification - Characterization goldens **byte-identical** before/after the move; reach-in sequence unchanged. - Full `ErsatzTV.Core.Tests`: **546 passed, 1 skipped, 0 failed** (TZ=UTC). - `grep` confirms no external callers of the old `PlayoutBuilder.Get*` statics remain. - `PlayoutBuilder.cs` de-BOM'd + whitespace-normalized per fix-as-you-touch (#311). ## Docs `docs/decisions.md` entry added (Index + append). Scheduling map unchanged (same engines/enumerators), so `domain-model.md`/`contributing.md` need no update. **Independent adversarial review + `Review-verdict:` to follow.** Live-E2E deliberately skipped: pure internal refactor, no `/api/*` endpoint or handler changed, and the playout-build path is exercised end-to-end by the golden tests against a real SQLite DB.
Author
Owner

Independent cold-context adversarial review complete (fresh reviewer, review-only, no implementation role). Verdict: MERGEABLE-WITH-NITS, all nits Low. It verified — via recovering the old method bodies and diffing, plus a mutation experiment (broke the moved method → the 3 intended characterization tests failed, then reverted) — that:

  • the move is byte-for-byte behavior-preserving modulo the ProgramSchedule→two-bool signature;
  • the signature change is provably equivalent (ProgramSchedule.TreatCollectionsAsShows genuinely defaults false; no other activeSchedule property was read);
  • all 4 call sites migrated, zero stale references;
  • the characterization tests are non-vacuous and pin the Shuffle/ShuffleInOrder paths (not just Chronological).

The one substantive nit — the untested keepMultiPartEpisodesTogether=true branch — is now closed by the follow-up test commit 5ce6040a (observably distinguishes the branches: 3 grouped vs 4 ungrouped). The other two nits (public vs internal accessibility; incidental de-BOM/whitespace churn in PlayoutBuilder.cs) are intentional and documented — no change.

The production surface is unchanged since the reviewed commit 99f845db; the only delta is the test-only commit above.

Review-verdict: MERGEABLE @ 5ce6040a88ea9ea97c49599effbb1fdaf7ffec44

Independent cold-context adversarial review complete (fresh reviewer, review-only, no implementation role). Verdict: **MERGEABLE-WITH-NITS**, all nits Low. It verified — via recovering the old method bodies and diffing, plus a **mutation experiment** (broke the moved method → the 3 intended characterization tests failed, then reverted) — that: - the move is byte-for-byte behavior-preserving modulo the `ProgramSchedule`→two-bool signature; - the signature change is provably equivalent (`ProgramSchedule.TreatCollectionsAsShows` genuinely defaults `false`; no other `activeSchedule` property was read); - all 4 call sites migrated, zero stale references; - the characterization tests are non-vacuous and pin the Shuffle/ShuffleInOrder paths (not just Chronological). The one substantive nit — the untested `keepMultiPartEpisodesTogether=true` branch — is now closed by the follow-up test commit `5ce6040a` (observably distinguishes the branches: 3 grouped vs 4 ungrouped). The other two nits (`public` vs `internal` accessibility; incidental de-BOM/whitespace churn in `PlayoutBuilder.cs`) are intentional and documented — no change. The production surface is unchanged since the reviewed commit `99f845db`; the only delta is the test-only commit above. Review-verdict: MERGEABLE @ 5ce6040a88ea9ea97c49599effbb1fdaf7ffec44
timothy force-pushed feat/380-enumerator-seam from 5ce6040a88 to f5cc27e902 2026-07-17 08:50:54 +02:00 Compare
Author
Owner

Rebased onto current origin/main (e1d77ebe, which merged #77 and #388) — main had advanced past the PR base. Conflicts were test/docs only and resolved additively:

  • PlayoutBuildGoldenTests.cs: kept both #77's Classic_clock_padded and this PR's Classic_shuffle (+ both in the Regenerate_goldens list). Also moved the shuffle fixture's channel to Number 4/GUID …0004 — #77's padded fixture independently took 3/…0003 and the shared in-memory DB tripped a UNIQUE constraint. Golden output unchanged (it snapshots times/titles; shuffle determinism is from playout.Seed).
  • docs/decisions.md: kept both 2026-07-17 entries (append-only) + both Index lines.

The production surface is byte-identical to the reviewed commit — git diff confirms origin/main (#77/#388) never touched PlayoutBuilder.cs / PlaylistEnumerator.cs / ShuffleSourceBuilder.cs, and the extraction diff to those three files is unchanged from what was reviewed. So the MERGEABLE verdict carries over; the rebase added only test-merge + docs-merge resolutions. Full ErsatzTV.Core.Tests re-run on the rebased tree: 549 passed, 1 skipped, 0 failed (TZ=UTC).

Review-verdict: MERGEABLE @ f5cc27e902

Rebased onto current `origin/main` (`e1d77ebe`, which merged #77 and #388) — main had advanced past the PR base. Conflicts were **test/docs only** and resolved additively: - `PlayoutBuildGoldenTests.cs`: kept **both** #77's `Classic_clock_padded` and this PR's `Classic_shuffle` (+ both in the `Regenerate_goldens` list). Also moved the shuffle fixture's channel to Number `4`/GUID `…0004` — #77's padded fixture independently took `3`/`…0003` and the shared in-memory DB tripped a `UNIQUE` constraint. Golden output unchanged (it snapshots times/titles; shuffle determinism is from `playout.Seed`). - `docs/decisions.md`: kept both 2026-07-17 entries (append-only) + both Index lines. **The production surface is byte-identical to the reviewed commit** — `git diff` confirms `origin/main` (#77/#388) never touched `PlayoutBuilder.cs` / `PlaylistEnumerator.cs` / `ShuffleSourceBuilder.cs`, and the extraction diff to those three files is unchanged from what was reviewed. So the MERGEABLE verdict carries over; the rebase added only test-merge + docs-merge resolutions. Full `ErsatzTV.Core.Tests` re-run on the rebased tree: **549 passed, 1 skipped, 0 failed** (TZ=UTC). Review-verdict: MERGEABLE @ f5cc27e9029d3035b493c8316784b140b2b0fade
timothy merged commit 5701f93625 into main 2026-07-17 09:05:15 +02:00
timothy deleted branch feat/380-enumerator-seam 2026-07-17 09:05:15 +02:00
Sign in to join this conversation.