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.
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.
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
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).
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
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Fixes #380.
What
Extracts the two shuffle-source helpers (
GetGroupedMediaItemsForShuffle,GetCollectionItemsForShuffleInOrder) out ofPlayoutBuilderinto a newpublic static class ShuffleSourceBuilder(ErsatzTV.Core/Scheduling). This eliminates the scheduler's one cross-engine reach-in:PlaylistEnumeratorwas calling those twoPlayoutBuilderstatics 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):MultiCollectionGrouper/MultiPartEpisodeGrouperand becausePlaylistEnumerator.Createis itself a static factory.PlayoutHistoryfamily); the Scripted≡YAML construction duplication → separate follow-up gated on #381 (no golden coverage there yet).One intentional signature change
GetGroupedMediaItemsForShufflenow takesbool keepMultiPartEpisodesTogether, bool treatCollectionsAsShowsinstead of aProgramSchedule(verified those are the only two properties it read). This deletesPlaylistEnumerator's fakenew ProgramSchedule { KeepMultiPartEpisodesTogether = false }(its TODO becomes an honestfalse, false) and gives future callers without aProgramSchedule(#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, pinnedPlayout.SeedviaContinuemode (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
ShuffleSourceBuilderTestsfor the branches goldens don't reach (multi-collection vs fake-multi-collection lookup; multi-part grouping on/off).Verification
ErsatzTV.Core.Tests: 546 passed, 1 skipped, 0 failed (TZ=UTC).grepconfirms no external callers of the oldPlayoutBuilder.Get*statics remain.PlayoutBuilder.csde-BOM'd + whitespace-normalized per fix-as-you-touch (#311).Docs
docs/decisions.mdentry added (Index + append). Scheduling map unchanged (same engines/enumerators), sodomain-model.md/contributing.mdneed 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.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:
ProgramSchedule→two-bool signature;ProgramSchedule.TreatCollectionsAsShowsgenuinely defaultsfalse; no otheractiveScheduleproperty was read);The one substantive nit — the untested
keepMultiPartEpisodesTogether=truebranch — is now closed by the follow-up test commit5ce6040a(observably distinguishes the branches: 3 grouped vs 4 ungrouped). The other two nits (publicvsinternalaccessibility; incidental de-BOM/whitespace churn inPlayoutBuilder.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
5ce6040a88tof5cc27e902Rebased 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'sClassic_clock_paddedand this PR'sClassic_shuffle(+ both in theRegenerate_goldenslist). Also moved the shuffle fixture's channel to Number4/GUID…0004— #77's padded fixture independently took3/…0003and the shared in-memory DB tripped aUNIQUEconstraint. Golden output unchanged (it snapshots times/titles; shuffle determinism is fromplayout.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 diffconfirmsorigin/main(#77/#388) never touchedPlayoutBuilder.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. FullErsatzTV.Core.Testsre-run on the rebased tree: 549 passed, 1 skipped, 0 failed (TZ=UTC).Review-verdict: MERGEABLE @
f5cc27e902