Skip to content

Loomarr Programming Heuristics — Channel Policy Design

Status: Living companion to design.md; implemented policy and future changes are labelled in place. Precedence: the main doc owns the subsystems (Suggester §8, Scheduler §9); this doc owns the programming intelligence that runs between them — what makes a generated channel feel like television instead of a playlist. Conflicts → main doc on architecture, this doc on heuristics; fix the loser in the same PR.


1. The prime principle: the LLM extracts, deterministic code enforces

Every heuristic in this doc splits into two halves:

  • Extraction (suggestion-time, §8 pipeline): the LLM interprets intent into a structured, schema-validated ChannelPolicy — “old-school Simpsons” → {series: [tmdb:456], seasons: {min:1, max:10}}; ”90s Saturday cartoons” → {audience: "kids", era: {from:1990, to:1999}, genres: ["Animation"]}.
  • Enforcement (schedule-time, §9 lineup builder): deterministic filters and constraint-aware slotting apply the policy. The LLM never places a program; it only proposes rules, and every rule it proposes is machine-checkable (grounding extends to policy: season ranges verified against the actual series, rating values from a closed enum, series ids resolved).

If enforcement lived in the model, one hallucination puts season 14 on the old-school channel. It doesn’t, so it can’t.

2. ChannelPolicy — the schema (the contract of this doc)

Stored per channel (JSON on the channel row), produced by the suggester, edited in proposal review and the channel editor, consumed by the lineup builder. Every field optional; omitted = global default (config-design.md §“per-channel tier”).

{
"scope": { // WHAT is allowed on this channel
"series": ["tmdb:456"], // resolved ids only — never names
"collections": [], // media-server collection (BoxSet) ids — §2.2
"seasons": {"min": 1, "max": 10}, // per-series season window
"era": {"from": 1990, "to": 1999}, // by first-air/release year, including episodes
"genres": {"include": ["Animation"], "exclude": ["Documentary"]},
"runtimeMax": 3600 // seconds; "nothing over an hour"
},
"audience": { // WHO it's for — safety-critical
"ceiling": "TV-Y7", // closed enum ladder (§4)
"unrated": "exclude" // exclude | allow — kids default: exclude
},
"separation": { // HOW OFTEN things may recur (§3)
"episodeNoRepeat": "168h", // same episode: once per window
"movieNoRepeat": "720h",
"seriesMinGap": "2h", // same series on MIXED channels
"blockMax": 2 // max consecutive slots from one series
},
"ordering": "syndication", // sequential | shuffle | syndication (§5)
"seasonal": { // WHEN in the year (§6)
"mode": "auto", // off | auto | exclusive
"holidays": ["halloween", "christmas"], // subset of built-in calendar
"strength": "featured", // light | featured | heavy — holiday episodes per day (§6)
"placement": "evenings" // evenings | anytime — when they air (§6)
}
}

An era applies at the playable programme boundary. A movie is judged by its release year; a series entry is judged once by its own first-air year and every expanded episode is judged again by that episode’s production year. This is what makes 1989–1999 Simpsons mean episodes from that period instead of every episode of a series that happened to begin in 1989. An episode whose year is unavailable passes the era check: scope is a taste filter rather than a safety boundary, and an episode the catalog has no year for must not empty a Channel. An explicit per-Lineup season window still narrows independently and wins by intersection.

scope.genres matches case-insensitively across two vocabularies. The suggester writes TMDB’s, whose TV genres include compounds (Action & Adventure, Sci-Fi & Fantasy, War & Politics), while an in-library entry carries the media server’s separate names (Action, Science Fiction). A compound therefore matches its parts in both directions, for include and exclude alike, but two parts never match each other. Exact-name matching excluded every series on a household channel scoped Sci-Fi & Fantasy / Action & Adventure and left it empty (#1630).

scope.dates is the only stored date scope (#1877). It keeps separate movie-release, series-premiere, and series-airing range lists under the date contract. Each list is a union; applicable lists compose by intersection. Title axes are checked before series expansion, and the airing axis checks the concrete episode year. A range may leave one end open (“1990 onwards”); set bounds are 1900–2099.

An era is a shortcut for dates, not a second scope: era R is scope.dates with movieRelease = seriesPremiere = seriesAiring = [R] (“era-shaped”), which filters exactly as the retired scope.era field did, on a channel scope and on a rule’s scope alike. The backend resolves the alias on decode, so a policy saved with era keeps its lineup without a migration, and it never writes era. Requests (channel PATCH, programming preview, AI refine input) still accept era; a request carrying both era and dates is rejected with 422 as ambiguous. A stored legacy scope carrying both decodes to their per-axis intersection, which is what the scheduler aired; where an axis’s windows miss the era entirely the era wins, since an empty list means “unconstrained” and cannot express “nothing”. A rule’s era now also filters each episode’s airing year, as the channel’s always did.

Explicit per-axis date windows are not widened to admit out-of-window model picks or by automatic relaxation; neither does an era-shaped scope (§7). The whole nonempty scope remains operator pinnable. Filler derives its own viewing-era union from the dates through the shared selection resolver: a single window seeds filler.era (which may be open-ended), a disjoint bounded union seeds filler.eraWindows; explicit scalar-era and range-list overrides are mutually exclusive. Programme-year and filler-year unknowns retain their distinct existing rules.

Single-series channels (a Simpsons channel) auto-relax seriesMinGap/blockMax — separation there means episode spacing, not series spacing. The relaxation is rule-based, not LLM judgment.

2.1 Ownership (who may write each field, and what a refine does)

The blob mixes three owners. This is structural in memory (Go groups the fields into a proposal sub-struct, an operator sub-struct, and reconcile output) but the wire JSON is flat and byte-identical to the schema above — the LLM emits and this doc publishes the flat shape; the grouping never reaches the wire (no migration).

  • Proposal-owned (scope, audience, separation, ordering, seasonal, and the seed of rules): the suggester extracts them; a fresh proposal (refine or re-curation) would normally refresh them.
  • Operator-owned (filler, window, autoCurate): never emitted by the LLM; edited only on the channel page and preserved across every re-approval.
  • Reconcile output (applied, the §7 relaxation record): enforcement writes it, the API surfaces it, it is rejected on write and recomputed each reconcile.

Operator edits are sticky (the ownership boundary). A proposal-owned field is refreshed by a later refine/re-curation only until the operator explicitly sets it; once set, it is marked operator-dirty (a persisted operatorSet list of field-paths, riding the flat blob — no migration) and a subsequent proposal cannot overwrite it. This is why the channel page can present era/ceiling/ordering/separation as directly editable without a refine silently reverting them. The audience ceiling is never relaxed even against a dirty value (the §4 safety asymmetry outranks stickiness — a dirty ceiling may be tightened by the fail-closed rules, never loosened).

⚠ An EMPTY proposal-owned field is never pinned. PATCH /v1/channels/{id} replaces policy wholesale — the operator’s values win as a unit — so a body that omits a field is indistinguishable from one that deliberately cleared it. Pinning on “changed from current” therefore records an edit the operator may never have made, and the failure is silent and permanent: the field is blanked and marked operator-dirty, so no later refine or re-curation can ever restore it.

Observed on the dev “1980s Action Heroes”: operatorSet: ["ordering", "scope"] with scope: {}. A single PATCH that changed ordering also carried an empty scope, which cleared the 1980s era window and pinned the emptiness. Six out-of-era titles (Guardians of the Galaxy 2014, The Rise of Skywalker 2019, Predator: Badlands 2025, …) then bound legitimately — enforcement was working, there was simply nothing left to enforce — and every re-curation since faithfully preserved a constraint that did not exist.

The rule: a pin protects a VALUE, and an empty field has no value to protect. Pinning one cannot preserve an operator’s intent (there is nothing to preserve); it can only prevent a future proposal from filling the field in. So an empty result is treated as “not set” regardless of how it got there, and the omitted-vs-cleared ambiguity stops mattering. The asymmetry decides it: a wrongly-pinned empty field is silent permanent data loss, while a wrongly-unpinned one means a later refine re-suggests an era the operator can see and change again.

This does not weaken stickiness, which exists so a refine cannot revert a deliberate operator value — every non-empty edit still pins exactly as before. Nor is it a licence for a partial-PATCH client: the FE still sends the whole policy ({...policy, scope: next}), because clearing a field the operator did set must remain expressible.

Rules merge by provenance. Each SchedulingRule carries a source (llm or operator) + stable id. A refresh proposal replaces only the llm rules and preserves the operator rules, so “make weekends a TNG marathon” expressed as a refine adds/updates an LLM rule while a hand-authored rule is untouched — refine and hand-authoring compose instead of one clobbering the other. (This supersedes the earlier “operator-locked after first seed” behavior.)

A refine that says “add Christmas specials during the holiday window” changes those LLM-authored rules, not the channel’s whole seasonal identity: the base policy remains year-round and the holiday:christmas rule activates its narrower slice on the calendar clock. “Turn this into a Christmas channel” is the distinct identity operation and grounds to seasonal exclusive. Grounding holds exclusive to the holidays the household’s country keeps (filler.home_country, #2030 decision 38): a holiday kept elsewhere is dropped from the subset, and a channel left with none plays year-round, with seasonNotKept naming what was dropped for the approval card. The model’s holiday ids are read loosely (“Christmas” is christmas) and an id no holiday has, or a group’s, is dropped first, so the card only ever names a real holiday. Holiday episode selection still honours the named holiday. The planner prompt lists that country’s holiday ids from the loaded definitions (decision 39). The same distinction applies to dayparts: morning/primetime/late-night curation is persisted policy evaluated by the scheduler for both newly proposed and existing channels, not a request to invoke the model at every clock boundary.

2.2 scope.collections — media-server collections, and why it is stamped

scope.collections restricts a channel to titles the operator has curated into a media-server collection (Emby/Jellyfin call these BoxSets; Kometa and similar tools write them). It is a hand-curated set — “my Halloween shelf” — which is precisely what makes it worth having: it is the one scope field whose membership is an explicit human judgment rather than derived metadata.

⚠ This is NOT LineupEntry.CollectionID, which is the TMDB franchise id (§5 ordering). Two different namespaces share the English word “collection”: a TMDB collection is an integer identifying a franchise (the Alien films), a BoxSet id is an opaque server-local string identifying a shelf someone made. They are never interchangeable, and a filter that compared one to the other would type-check and silently match nothing. The Go field is therefore named BoxSetIDs, in the media server’s own vocabulary, so the two cannot be confused at the point of use. The wire/DTO name stays collections (it is what an operator calls it).

Membership is STAMPED on the entry and healed at reconcile, exactly like OfficialRating (§4) and CollectionID (§5), for the reason those two are: filterEntries is a pure function over []LineupEntry with no per-reconcile library I/O, and that property is load-bearing for scheduling latency rather than incidental. Resolving BoxSet membership inside the filter would put a media-server round trip on the scheduling path, per entry, per pass — the N+1 shape that dominated the guide-latency work (1910ms → 103ms; the first fix was removing exactly this).

⚠ The CollectionID tri-state does not transfer, and the difference is a real trap. -1 works as “resolved, standalone” because the field is an int. BoxSetIDs is a []string, where “not resolved yet” and “resolved, belongs to no collection” are both empty — so an entry in no BoxSet would be re-fetched on every reconcile forever, reintroducing the N+1 through the back door for the most common case. Resolution state is therefore carried by an explicit BoxSetsResolved bool, not by nil-vs-empty: the entry is JSON-persisted, and a nil/empty slice distinction does not survive a round trip through encoding/json, let alone a later refactor.

The consequence, stated plainly: adding a title to a BoxSet in Emby takes effect on the channel’s next reconcile, not instantly. That is the deliberate trade for keeping the scheduler I/O-free, and it matches how a rating change already propagates.

Fail-OPEN, unlike audience. An unresolved entry (BoxSetsResolved == false) is not filtered out — a media server that is down or slow must not silently empty a channel’s lineup. This is the opposite of the §4 audience ceiling, and the asymmetry is the same one §4 states: a missing rating risks showing adult content to a kids channel, so it fails closed; a missing collection membership risks showing an in-library title the operator did not shelve, which is a taste miss, not a safety one. Scope is never a safety property (see the era grandfathering rule).

3. Separation & repetition (“don’t show the same thing twice in a row”)

Tunarr lineups are cycles — an ordered list that loops. So separation is enforced along the cycle timeline including the wrap: the last Simpsons block and the first must also honor the gap, or the loop seam betrays the illusion.

  • Hard floors: episodeNoRepeat (an episode appears once per window), movieNoRepeat (longer — a movie reappearing in a week feels cheap).
  • Multi-part episodes stay together (a hard adjacency floor). A two-parter (“The Best of Both Worlds (1)/(2)”, “All Good Things… (1)/(2)”) must air as an atomic, in-order block — Part 2 immediately after Part 1, never scattered by the shuffle or split by the rolling window (showing Part 2 with Part 1 out-of-window is worse than out-of-order). Detection is deterministic at episode-resolution time, from either signal: (a) the media server’s IndexNumberEnd (a single file spanning e.g. episodes 25–26), or (b) a shared title base with a (1)/(2) or Part N suffix on consecutive episodes of the same season (the two-separate-files case, which is the common one). Grouped episodes carry a shared group id + within-group index; ordering (syndication/shuffle) permutes the group’s position but never its internals, and the rolling-window truncation keeps a group whole (a group is one unit for the window budget). This is a floor, not a policy knob — a channel never wants a split two-parter.
  • Movie franchises stay together, in release order (the same floor, for films). A franchise’s films (“Raiders of the Lost Ark” → “Temple of Doom” → “Last Crusade”) must air as an atomic, in-release-order block, never scattered by the shuffle (the reported bug: Temple → Crusade → [unrelated film] → Raiders). Detection is the TMDB collection (belongs_to_collection.id) — the authoritative signal, because it groups “Raiders of the Lost Ark” with the “Indiana Jones and the…” films even though they share no title base (a title heuristic can’t). The collection id is resolved at reconcile (a per-movie TMDB lookup, healed onto the entry like OfficialRating — a tri-state field: 0 unresolved, >0 a collection, -1 resolved-standalone, so it’s a one-time repair, not a per-sweep call) and stamped onto the lineup entry, so the pure scheduler stays I/O-free. Films sharing a collection get a shared group id + a release-year within-group index, then flow through the same collapse/expand atomicity as multi-part episodes — one mechanism, two sources (episode parts, franchise films). A collection with fewer than two present films isn’t grouped (nothing to keep it with). Requires TMDB configured; without it, films simply aren’t grouped (no worse than before).
  • Cycle-length consequence: the no-repeat window implies a minimum pool size. If the pool can’t fill the window, do not fail and do not silently violate — descend the relaxation ladder (§7).
  • All slotting is seeded-deterministic (seed = channel + cycle index, extending the main doc’s pod rule) — same pool + same policy + same seed = same cycle, so tests reproduce exactly.

3.1. Recency (“don’t bring back what just played”)

Everything in §3 is within-cycle. When the cycle wraps, the deck replays from position and the scheduler’s memory resets to nothing — so a title recurs on a fixed positional clock rather than a programmed one. Reported from the dev channel: Akira at Tue 21:53, Fri 13:33, Sat 02:10, Mon 01:30 — four airings in a week, at no interval anyone chose.

Recency closes that loop using airings (design.md §5): the last time each episode or film aired on this channel, consumed at placement.

  • Per episode, not per title. An aired episode moves back; its unaired siblings keep their places. Keyed by the series, one tune-in pushed a whole show behind everything else (#1674).

  • Read as of the window’s start. A window’s arrangement reads the history recorded before the window opened, so it is constant for the whole window, like the slice offset. What airs during the window shapes the next one. Read live, every reconcile after a tune-in re-sorted the deck and the guide rewrote the programme on air (#1674). An unbounded window never opens a new one, so it reads no history. Library facts do not re-arrange the window either, and an edit re-arranges only what follows the programme on air (#4140; docs/design/scheduling.md, “Nothing that has aired moves inside a window”).

  • A SOFT RANKING SIGNAL, not a constraint. Among candidates that are equally valid under every §3 rule, the least-recently-aired wins; a title that has never aired sorts first. It cannot be “violated”, so it has no ladder step (§7) and never emits a relaxation note.

  • ⚠ Why soft, and why this is the honest design. A hard “no repeat within N days” is arithmetically unsatisfiable on a real channel: a 24h day consumes ~13 films, so a week without repeats needs ~168h of content, and the dev channel has ~62h. Even 3 days is impossible there. A constraint that fails on every run produces a relaxation note on every run, and a ladder that always fires is a ladder operators learn to ignore — it would make the §7 output less trustworthy in exchange for a guarantee that was never available.

  • What it does and does not fix. It spreads airings evenly and stops a title clustering near its own last showing, so repeats read as rotation rather than randomness. It does not make repeats rare: at 62h of content everything returns within ~2.5 days no matter how it is ordered. Only more content changes that frequency, which is what re-curation and adjacency candidates (§8.2/§8.3) are for. Saying so here is deliberate — an operator who reads “recency-aware” as “won’t repeat” will file the same complaint again.

  • Determinism holds. Last-aired timestamps are an input, so the same pool + policy + seed + history reproduce the same cycle. Tests pin history explicitly rather than relying on a clock.

  • Degrades to today’s behaviour. No history (a fresh install, a channel that has never aired, a store that cannot answer) ⇒ every candidate sorts equal and placement is exactly what it was before this existed. The signal is additive, never load-bearing.

4. Audience safety (“Saturday cartoons must never go adult”)

The one heuristic where an error is a harm, not an aesthetic bug — so it fails closed:

  • ceiling is a closed ordered ladder spanning both TV and film systems: TV-Y < TV-Y7 < TV-G/G < TV-PG/PG < TV-14/PG-13 < TV-MA/R/NC-17. Enforcement compares the item’s OfficialRating (same field name on Emby and Jellyfin) mapped into the ladder; unmappable strings are treated as unrated.
  • The ceiling is enforced TWICE: on the entry, and again on every expanded episode. A series entry is gated at its series rating in filterEntries — but that rating is a lossy summary, so resolveEntry re-checks each episode as it expands (episodeVerdict), and an episode rated above the ceiling is dropped even though its parent cleared the gate. A series whose every episode is refused resolves to nothing, never a pending slot: a pending slot means “approved, still acquiring”, which advertises the title and (under PodFill) holds airtime for it — a show the ceiling refused is not late, it is excluded.
    • ⚠ This paragraph used to say the opposite, and called it safe. It described entry-only gating as “a small, deliberate safety narrowing … at worst a below-ceiling series with an occasional harder episode is admitted” — which is not a narrowing, it is the leak, stated as if it were the mitigation. Live proof (2026-08-10, maintainer’s library): 90s Cartoon Classics, ceiling: TV-PG, aired King of the Hill — a TV-PG series whose 275 episodes are 253 × TV-PG, 2 × TV-14, and 20 × unrated. TMDB lists both TV-PG and TV-14 for the show. South Park and Futurama were dropped correctly at the entry gate, which is what made the leak look like correct behaviour.
    • An episode with no rating of its own INHERITS its parent’s rather than failing closed — the one place §4’s “never guess” is deliberately not applied. The parent has already cleared the ceiling as a whole title, so inheriting falls back to a check that just ran rather than guessing at unknown content; blank episode ratings are a metadata gap (20 of those 275) and refusing them would silently drop ~7% of an approved show. The asymmetry still holds where it counts: an episode that is rated is judged on its own rating and can never be lifted by a permissive parent.
    • The rating/genres/year an entry is filtered on are stamped onto the channel’s approved lineup entry at create time (when the full grounded candidate is in hand). Episode ratings and production years come with the series’ episodes from the Library’s tables (LibraryEpisodes), so both gates stay pure entry/slot-set filters.
  • Kids ceilings (TV-Y…TV-PG) default unrated: "exclude" — an item with missing or unmappable rating metadata is excluded, never guessed at. Metadata gaps are the real-world failure mode; a kids’ channel must be safe against them by construction. Adult/general channels default allow. An explicit exclude binds with or without a ceiling; with no ceiling all mapped ratings remain eligible. Episode parent-rating inheritance still applies.
  • Transparency at review: the proposal shows the policy’s effect — so gaps are visible before approval, and the fix (rate your media, or relax the policy) is a human decision.
    • The suggester REFUSES its own unairable picks (refuseUnairable, after groundPolicy). A grounded pick whose known rating is above the extracted ceiling is moved out of Lineup/Acquisitions into Proposal.Refused with the same over_ceiling vocabulary §4 uses elsewhere, and the approval card names it. ⚠ Refused, not deleted — the operator’s usual fix is to raise the ceiling, and a pick that vanished between the model’s answer and the approval screen is indistinguishable from one the model never made. It is not provisioned either: approval acts only on what it offered.
    • The refusal runs after groundPolicy, so every pick is judged against the final deterministic ceiling shown for approval.
    • An UNRATED pick is refused when the intent explicitly requires child safety. The refusal uses over_ceiling, the same operator-facing safety reason as a known harder rating. Rating enrichment and reconcile healing remain useful for ordinary family/teen proposals, but an explicit child-safety request cannot make unknown content actionable while waiting for metadata.
    • ⚠ This closes a hole in the AUTHORIZATION model, not just a display gap. Approval is the gate (design.md §7/§11); until this, it presented choices that were silently discarded downstream — the operator approved seven titles and got five — which teaches that the list is approximate, exactly the property approving exists to deny. Found live 2026-08-10 on a TV-PG ”90s Saturday morning cartoons” channel that proposed South Park (TV-MA) and Futurama (TV-14).
  • Explicit rating maxima (capped at PG, nothing above PG, PG ceiling, PG or gentler) are deterministic constraints even if the model omits policy. Match complete rating tokens; preserve the stricter of multiple maxima. Explicit unrated exclusion also survives omitted or looser model policy and refuses unknown ratings before approval, with or without a rating cap. A negated exclusion or an unrelated rating/title mention does not create that constraint.
  • The LLM may infer the ceiling from intent, but it does not own the safety boundary. Explicit child-safety language (kid-safe, for kids, safe for children, preschool/toddler, or Saturday-morning kids programming) deterministically imposes a maximum of TV-Y7, even when the model omits a ceiling or proposes a looser one. A model may propose a stricter ceiling; it may never relax this bound. The final value is shown as an editable chip in review, and enforcement is the ladder comparison.
  • The ceiling is a kids/teen guardrail, not a general default — omit it unless the intent asks for one. The audience ceiling exists for one purpose: so a channel a user asked to be for kids or teens can never show adult content. An unqualified channel is an adult-default channel — “1980s Action Heroes” obviously includes its R-rated films (Die Hard, Predator, The Terminator). So a proposed ceiling is kept only when the intent carries a kids/teen signal (words like “kids”, “family”, “cartoons”, “all ages”, a named kids property like “Bluey”, an explicit low rating like “TV-Y”, or a kids daypart). With no such signal, any model-proposed ceiling is dropped (→ no ceiling, everything admitted) — a small model’s reflexive “action might be violent, better cap it at TV-14” must not silently strip the R-rated content the channel is about. This is enforced deterministically in groundPolicy (the prompt says “adult/no mention → omit,” but the model isn’t trusted to obey it). The safety asymmetry is absolute: dropping an unjustified ceiling only ever loosens (a content choice, reversible by the operator); when a kids/teen signal is present the ceiling stays and is enforced fail-closed. Grounded picks never raise a ceiling: a known harder title is refused, and an explicit child-safety request also refuses unrated titles. Loosen freely on adult channels; never loosen a kids channel.
  • The model proposes no date scope. Its policy carries no era. A proposal’s scope.dates comes only from the validated date meaning, and those explicit windows are not widened to admit picks (§2).

5. Ordering modes (“feels like TV”)

  • sequential — S1E1 onward, loops at the end (binge/marathon channels).

  • shuffle — seeded random, separation-constrained. The seed is the channel’s own. A channel that stores none (every binder-made channel stores 0) derives it from its id (FNV-1a), stable for the channel’s life and needing no migration, so two channels over the same pool deal different decks. It reshuffles each pass, exactly as syndication does (below and §6.5).

  • syndication (default for TV) — random without repeats until the eligible pool exhausts, then reshuffle (a “deck deal”): the authentic weekday-rerun texture, and it makes episodeNoRepeat nearly free because the deck is a no-repeat structure. Each deck reshuffles under seed XOR deckIndex so successive decks differ yet every deck is deterministic for a given channel seed (the §7-mandated reproducibility). The deck index is the pass of the rolling window around the catalog (§6.5), counted from the channel’s creation.

  • Omitted ordering inherits the channel’s Strategy. A channel created without an explicit policy ordering keeps its existing sequential/shuffle behavior — the syndication default applies only when a policy explicitly requests it (or a template ships it). This keeps policy adoption non-breaking for existing channels.

  • One operator knob, one canonical precedence ladder. Ordering resolves in exactly this order: per-rule How.Ordering (within that rule’s active window, §6.5) > policy.ordering > Channel.Strategy (the create-time stored default). policy.ordering is the operator-facing knob (edited in Programming → How it’s ordered); Channel.Strategy is the default the binder seeds and is consulted only on inherit — it is not a second editable field (design.md §9). A rule’s How overrides only for the slots that rule governs; outside any rule window, the base policy.ordering applies. This is the single ladder that makes “three ways to express ordering” read as one.

  • Rerun curation and narrative order are different promises. A channel whose lineup is several series (a “Star Trek” franchise channel) defaults to syndication so the shows intermix instead of playing one to completion. A clearly curated single-series intent (classic Simpsons, best episodes, favorites, highlights, reruns) also resolves to syndication: its eligible season window is a pool to curate into a deterministic no-repeat deck, not an instruction to start at S1E1. Explicit chronological, start-to-finish, binge, or marathon language forces sequential, even when the model proposed shuffle or syndication. One series plus movies is not inferred as either case. This episodic rule does not loosen the movie-franchise floor above: films sharing a TMDB collection remain one atomic, in-release-order block even when the surrounding channel is shuffled or syndicated. The prompt guides the model, and groundPolicy enforces both deterministic outcomes so a small model cannot turn a rerun request into a box-set binge or a binge into a mixed deck.

  • Episode selection precedes episode ordering. Every proposed series carries one proposal-owned closed mode through approval into its Lineup entry: complete, highlights, or holiday. Omitted/unknown legacy data means complete. Code derives the mode from explicit Intent after grounding; the model never names episodes or chooses the mode. Whole-word classic/best plus favorites, reruns, curated, or highlights language selects highlights; explicit chronological, start-to-finish, binge, or marathon language selects complete. A named built-in holiday selects only that holiday; explicit generic “holiday episodes/specials” selects across the closed built-in holiday vocabulary. Named holiday detection uses the shared Unicode-normalized whole-phrase matcher over every affirmative Intent field, including ordinary refine text such as “add Christmas specials”; “Christmasland” and “Valentinesque” are not holiday cues. mustExclude remains a negative grounding constraint and cannot trigger or suppress a positive episode mode. Holiday specificity wins over narrative ordering, so a chronological Christmas request selects Christmas episodes and orders only that pool sequentially. Built-in holiday ids and aliases have one immutable domain owner shared by Intent recognition and scheduler evidence/calendar matching. Calendar dates remain scheduler-owned and bind to those ids; no caller carries a parallel alias table.

    Editorial selection requires current editorial evidence. An episode-resolution result carries the safe playable deck and whether that evidence is available, rather than encoding freshness by blanking episode fields or asking schedulers to inspect cache state. An aged cache is live-refreshed; if refresh fails, a non-empty valid cached deck remains subject to the same season, era, and audience filters; highlights may use that complete safe deck, while a holiday selector has no current matching evidence and selects no episodes. An aged empty cache with failed refresh is unavailable. Fresh and successfully refreshed decks permit their declared editorial mode.

    Selection receives the pool only after season, era, and audience gates. It treats each standalone episode or detected multi-part story as one atomic unit, and returns units in canonical order for the existing ordering engine to place. A multi-part unit is rated only when every part has a valid rating, using the arithmetic mean of its part ratings; one missing/invalid part makes the unit unrated. highlights uses the Library’s aggregate community rating only as a relative cohort signal: at least eight units must exist, at least 75% must carry a finite rating in (0,10], and the chosen pool is the upper rated quartile with a four-unit floor and a 48-unit cap. All units tied at the cutoff are included; a tie that consumes the rated cohort or exceeds the cap falls back to complete. The 75% floor prevents a sparse rated minority from defining “best”; four keeps a usable rerun deck; 48 bounds long-running series. Emby/Jellyfin does not expose rating vote counts, so cohort coverage is the only supported confidence gate: this slice makes no absolute-confidence claim and performs no scheduler-time enrichment call.

    One episode-evidence codec owns the rating and text/tag domain. A lineup’s series expands from the Library’s tables (LibraryEpisodes, #2151 step 16), and the episode resolver runs every row through the same playable check and sanitizer the media-server adapter’s JSON decoding uses, so no source can bypass the bounds. Malformed editorial rating/text/tag JSON becomes unavailable evidence and unknown fields are ignored. A malformed mixed-type tag array makes the entire tag field unavailable; no successfully decoded prefix survives. Exact or Unicode-case-fold duplicate editorial members are also unavailable: the decoder preserves/counts object-member occurrences instead of accepting a map-iteration or last-member winner. Editorial corruption does not discard neighboring valid episodes, while an episode without a non-blank Library item id, positive runtime, non-negative season, positive episode number, and an episode end of zero or at least the starting episode is dropped, because scheduling cannot safely invent those facts or emit a blank/zero-duration slot. A series with no playable episodes expands to nothing.

    holiday applies the §6 holiday judgment to the episode title, bounded overview, tags and original air date, restricted to the selected holiday ids (empty means all built-ins), and selects episodes judged about or adjacent; a mood word such as “a ghost” in an ordinary overview is not holiday evidence. Generic holiday text and a Santa mention naming Santa’s Little Helper do not establish Christmas membership; separate Christmas evidence in the same episode still counts. No matching or unavailable holiday evidence selects no episodes, including during an off-season loop. Sparse highlight ratings, malformed mode, or unavailable highlight evidence retain the complete already-safe pool. Selection never restores an audience/scope rejection. An unavailable requested holiday selection is reported honestly. Proposal review renders the mode before approval as All episodes, Curated highlights, or the named/generic holiday episode scope.

    ApplyLineup same-key replacement preserves the approved mode when the lossy lineup edit DTO omits it. Reordering or renaming a series therefore cannot silently reset highlights/holiday to complete. At approval, after all search additions and drops, the one server approval gate re-stamps every series in the lineup, acquisitions, and alternates from the Proposal’s original Intent before Proposal serialisation and Lineup binding. Generation applies the same grounding to all three collections, so an alternate promoted later cannot silently default to a complete deck. Missing or client-injected modes therefore cannot cross the approval boundary; movies remain selector-free because episode selection does not apply to them. A dropped provisioning key is filtered from lineup, acquisitions, and alternates before this stamping step, so a title explicitly excluded during review cannot return as a backup. The same gate rejects a human edit that leaves neither a lineup nor an acquisition title; a client-side selected count is guidance, not the authority protecting against an empty edited Channel. An automatic re-curation may approve a nil incoming delta because the existing Channel remains intact. Before approval, the proposal API exposes one read-only selection preview derived server-side from the same trusted Intent. Search-added series rows render that preview even when the proposal originally contained only movies. The client does not parse cues or submit the projection; approval still re-derives and replaces every series selector before persistence.

6. Seasonality (“holiday episodes at holiday time — and only then”)

Two symmetric behaviors, because knowing what October wants implies knowing what July doesn’t:

  • Detection is a judgment of what a title is about, with a deterministic floor (#1670). The calendar is the household country’s (filler.home_country; empty, or a country no definition names, keeps the US calendar every household had before countries; #2030): each holiday is one definition in internal/platform/holidayvocab (its words and, per country, a day rule and the window around it), evaluated on guide.timezone, and programming, the on-screen logo and filler read the same one. The US keeps Halloween (Oct 1–31), Thanksgiving (Nov 15–30), Christmas (Dec 1–26), New Year (Dec 27–Jan 2), Valentine’s (Feb 1–14), Easter, Mother’s and Father’s Day, St Patrick’s, Independence Day, Memorial Day and back-to-school; Canada, Britain, Ireland, Australia and New Zealand keep their own set and dates (Canada’s Thanksgiving in October, Mothering Sunday three weeks before Easter, Boxing Day inside Christmas, back-to-school in the southern summer). A holiday added after v1 benches an out-of-season title only on evidence beyond its name (an in-window premiere or corroborating genres), since “Easter” or “Independence Day” in a title says less than “Halloween”. Definitions are data in the holidays table: boot stores the shipped ones once per seed revision, never over an operator’s edit or retirement, and each holiday owns the seasonal taxon of its id (the taxonomy editor adds an undated holiday with a new seasonal taxon and retires it with the taxon, but refuses to retire a dated or group holiday). A seasonal taxon from before holidays were data becomes an undated holiday whose clips air year-round. The server reads one validated snapshot, reloaded after its own edits and every 30 seconds for the other replicas, and keeps the last good snapshot if stored rows fail validation. GET /v1/holidays serves the definitions with this year’s season for the household country. Editing holidays in the app is #2030’s later work.
    • Verdict vocabulary. For one (title or episode, holiday) pair the answer is closed: about (the holiday is its subject or setting), adjacent (it fits the holiday’s mood without being about it — a haunted-house horror film for Halloween), or not. Each verdict carries a short reason code that clients word (“Halloween in the title”, “Halloween keyword”, “a haunted-house horror film”). One owner, internal/platform/holidayvocab, judges; the scheduler, Channel ideas and the suggester all call it.
    • The floor (always on; the only judge while the LLM is off, unavailable or undecided). Each holiday has name aliases (the holiday itself: “halloween”; “christmas”, “xmas”, “santa”; …) and mood aliases (“ghost”, “haunted”, “witch”, “spooky”, “horror”). A name alias in the title, the overview or media-server tags, or a TMDB keyword naming the holiday (Halloween keyword 3335), is about. A mood alias in the title or keywords is adjacent only when the genres corroborate the mood — Halloween: Horror, or a family genre (Family, Children, Kids, Animation) together with Fantasy, which keeps a teenage-witch sitcom or a friendly-ghost cartoon; a bare mood word never counts alone. So Ghost World (Comedy, Drama), Mission: Impossible – Ghost Protocol (Action) and Ghost (Fantasy, Romance — no family genre) are not, while The Witch (Horror) is adjacent. A name alias inside a known look-alike is not the holiday: Santa’s Little Helper, Santa Clarita and other Santa place names, Bill Nye.
    • Episodes: the original air date. Episodes carry no genres, but broadcast holiday episodes premiere near the holiday, and the media server’s PremiereDate is cached per episode (AirDate). An episode whose original air date falls in the holiday’s broadcast window and that has a mood alias in its title or overview is about — an animated sitcom’s annual Halloween anthology whose overviews never say “Halloween” is proved by its late-October premieres. A mood alias in an episode’s title with no air date in the window is adjacent (an episode title describes that one episode, unlike a film title such as Ghost World); a mood alias only in an ordinary overview is not. An air date alone is never evidence: plenty of ordinary episodes air in late October. Broadcast windows: Halloween Oct 15–Nov 7, Thanksgiving the seven days before the fourth Thursday of November through the Sunday after, Christmas Dec 1–Jan 2, New Year Dec 26–Jan 7, Valentine’s Feb 7–21 (only Halloween has mood aliases today, so only its window decides anything yet). Cached episode lists written before the date was kept simply lack it — judged as “no date” — until the library refresh repopulates them. With the LLM off, the floor alone builds the holiday’s Channel idea, and it is not offered below its minimum title count. Genres corroborate a mood word; a genre alone is never evidence (the correction below still holds).
    • The judgment (when the configured LLM is available; planned, #1670 — until it ships the floor is the only judge, and the review reasons and removal feedback below arrive with it). A background job (holiday-judgment, daily and after a library refresh) batches candidates — titles with any floor signal, any holiday TMDB keyword, or a mood genre — into one compact closed-vocabulary call per holiday per refresh: at most 12 items of (id, title, year, genres, ≤200-character overview, keywords) per call, answer {"id": ..., "verdict": "about|adjacent|not", "reason": "<≤6 words>"}. Grounding drops unknown ids and malformed verdicts; an item the model skipped keeps its floor verdict. Verdicts are cached per (item, holiday, metadata revision — a hash of the fields sent), so pages and the scheduler read the cache and never wait on a model; changed metadata re-judges. TMDB keywords are fetched per title by the same job (cached with the verdict revision, throttled well under TMDB’s limit), never on a request path. Episodes are judged on the same path (episode title + overview), only for series on channels where seasonal applies, cached per episode.
    • Combining. A household’s removal of a pick for a holiday (below) is not and wins. Otherwise a floor about stands (a title named for the holiday is about it); a cached model verdict decides everything else; with no model verdict the floor’s answer stands.
    • What acts on which verdict. Out-of-season benching and in-window boost in auto need about — a false bench silently removes programming, so a mood word or an adjacent verdict never benches. exclusive in-window membership, holiday episode selection and the Channel idea for a holiday accept about or adjacent.
    • Visible and correctable. A holiday idea’s proposal review shows each pick’s reason. Removing a pick there is remembered as discovery feedback scoped to that holiday (scope=holiday, action=never), which the next idea, judgment and bench honour for the whole household.
    • Entry and episode scope. Entry-level seasonal bench/boost continues to match a movie or series title only. An explicitly holiday-curated series additionally carries a per-entry holiday episode selector; after episode safety/scope filtering it judges the episode’s title, overview, media-server tags and original air date against only the named holiday ids. This supports “Christmas Simpsons episodes” without mistaking every Comedy or Family episode for a holiday episode. In an active exclusive window, defer series membership to those concrete episode facts: a non-holiday series title cannot exclude its holiday episodes, and a holiday series title cannot certify every episode. After safety/date/season filtering and multipart grouping, retain the units supported by the active holiday ids. Preserve complete supported multipart units and their ordering. No matching or current editorial evidence means an explicit seasonal exclusion, not the ordinary editorial selector’s full-run fallback or an acquisition placeholder. Genuine unavailability still follows the pending policy. This deferred filter does not change movie detection, ordinary auto/off, zero-clock behavior, or the exclusive off-season loop/dark contract. Calendar exclusion does not remove library availability from drift evidence.
    • ⚠ A genre is never evidence on its own, and this is a correction (genres only corroborate a mood word into adjacent, which never benches). Detection originally hayed over title + genres, which conflated “this title is about a holiday” with “this title belongs to a genre that correlates with one”. Those are different claims, and only the first is what a holiday window should act on. The failure was total rather than cosmetic: horror sat in the Halloween keyword set, so on a year-round horror channel every entry detected as seasonal, and auto mode benched all of them out_of_season for the eleven months outside October. The channel was legal to configure, reported live, and aired nothing. A genre is what a channel is; a holiday keyword is what a title is about. The rule’s own example — Christmas episodes in July break the spell — is a title, and the fix restores exactly that reading. (A single genre-shaped keyword could have been dropped instead, but the mechanism would have re-fired on the next collision: a Romance channel near Valentine’s, a Family channel near Christmas.)
  • mode: "auto" (default): in-window, seasonal items get a scheduling boost (weighted up, tasteful — not wall-to-wall); out-of-window, detected-seasonal items are benched (excluded). The bench is the half everyone forgets and the one viewers notice: Christmas episodes in July break the spell.
  • Holiday episodes inside an ordinary series (auto only, #1670). The title-level boost cannot see that The Simpsons holds nine Treehouse of Horror episodes: the series title is not about Halloween, so before this an October channel aired them only when the deck happened to deal one. In auto mode the scheduler now features those episodes, matched by the same episode evidence exclusive uses (title, overview, tags; episodeHolidays). A series whose own title is seasonal keeps the entry-level bench/boost and is not featured twice.
    • One plan per day. Each channel-local civil date of an active holiday window has one plan: which pool episodes it features and the time each is due. The plan does not depend on the rolling window’s length; a window airs the features due inside it (opening ≤ at < closing), so a 6-hour, 12-hour, daily or 3-day window airs the same day the same way, and never twice. The pool is the deck’s holiday episodes for that date’s active selected holidays, in deck order. The deck order never changes.
    • Where it runs: the season simulation (#1939). A window is in season when any date it touches has a non-empty pool. In-season windows, and the first out-of-season windows after one (the horizon: twice the windows the repeat spacing spans, plus one), are not cut independently. They are simulated in order from the season’s anchor: its first in-season window, found by walking back over in-season windows and gaps no longer than the horizon, at most 120 days. Two seasons closer than the horizon are one simulation. Every other window is the dealer’s tile (windowSliceDealt), arranged. After the simulation comes the hand-off (handOff), where the season’s tiles still sit inside the repeat spacing. The dealer repaired each seam against the deal before it, so while any window the spacing reaches back over aired otherwise than the dealer alone would, the next window’s deal is arranged and then repaired against what really aired (#2001):
      • Each unit is owed the spacing, or the gap the dealer’s own arrangement gives it when that is less. Holding every unit to the full spacing moved units the dealer rests less, so the hand-off never settled.
      • A unit that has not rested what it is owed is held back in the window until it has. One that cannot rest before the window closes is swapped, in its slot, for a unit that has rested the spacing, preferring one that also rests it before its next deal. The window keeps its length: a window one unit short loops its head, which aired a window ago. An off-season holiday episode is only ever held back, never swapped out, so it is still never benched.
      • The repaired order is what airs. Arrange does not move it again: a swap out of the evening, checked against the windows around as dealt, brought a unit the repair had held back into the evening, inside the spacing.
      • The hand-off ends once every window the spacing reaches has aired as the dealer alone would. Over 120 deal origins that took up to 15 windows (a 400-episode deck in daily windows), more than the horizon, so it runs until it settles, for at most four horizons. It reads back over every window the spacing spans, not only the window before: a 12-hour spacing on a 6-hour window reaches two windows back (#1960).
      • The simulation’s last windows prefer, when topping up, a unit that has rested since its last airing but is due again soon after the simulation over one that has not rested: the hand-off holds the first back, and nothing can save the second. Its settle step holds a unit that rested too little back in the window before keeping it where it is. The simulation keeps airedAt, each unit’s last airing as a programme index that counts the features. Before the anchor it holds the dealer’s tiles, arranged, covering at least the repeat spacing. For each window in turn:
      1. Take the dealer’s tile for the window. Drop the pool, and any unit that would air sooner than the spacing after its last airing. A deck that fits one window drops only the pool.
      2. Keep units in deal order until their runtime meets the window less its features’ runtime. Units cut here are owed.
      3. Top up a short tile with ordinary episodes. Owed units go first, in deal order. Then any ordinary unit of the pass. The preferences, in order: not aired by the window before and not dealt to the next; at least the spacing from its last actual airing and from its next dealt airing; the farthest from both.
      4. Arrange the window around its features, and check each unit where it really airs: an off-season holiday episode leaving the evening pulls the units after it earlier than their place in the tile. A unit now sooner than the spacing is dropped for the window and the tile topped up again without it (step 3); each pass drops one unit, so it ends.
      5. Record every programme’s index in airedAt. Every decision reads what actually aired, never a ring position. A feature is decided by its day’s plan. Its airing enters airedAt, so the windows after the season (and after a holiday date) trade away a unit the season just featured, like any recent airing. The holiday date itself keeps its whole plan. The spacing promised is the dealer’s repeat spacing for Shuffled and Syndication (two windows and a unit, §3.1). For In order, the dealer has none, so the simulation uses half the deck less its holiday episodes. One simulation serves the season. It is memoised by the dealer’s inputs (seed, window, policy, collapsed slots), the ring origin, zone, holiday evidence, break density and the anchor and end windows, in a small LRU like the deal chain. A guide request therefore simulates once per season per lineup, and an edit lands on a new key. A pool with airing history is not shared. One run costs O(windows × deck): each top-up scans the pass once. A deck that fits one window airs whole, minus the pool, every window. Recency (tradeRecent, #1694) then guards the tile as it does any tile. The pass is a pure function of (deck, window index, zone, policy): it is idempotent within a window, there is no mid-window reshuffle (#1674/#1675), and the cycle-cache key needs nothing new. A channel with no rolling window (window: full) has no wall-clock anchor and is untouched.
    • Strength (seasonal.strength, default featured). Per ordinary day of the window: Light 1, Featured 3, Heavy 5. A day features at most ⌊day length ÷ (mean programme runtime × break density) ÷ 4⌋, so the rest of the lineup keeps three quarters of the day. The day length counts the 23-hour and 25-hour daylight-saving days, and the result can be 0. The cap is applied before the rotation, so a capped pool still rotates evenly.
    • The holiday’s own date (Oct 31, fourth Thursday of November, Dec 25, Dec 31, Feb 14) is the one exception. It features the day’s ring picks plus extras, in ring order, up to the strength’s holiday quota: Heavy every holiday episode, Featured up to 5, Light its 1. Extras prefer episodes the day before and the day after would not feature. The day before and the day after then drop anything the holiday date airs, compared by episode because neighbouring pools can differ (Christmas, then New Year). So no episode airs on the holiday and on either neighbour. Heavy’s whole-pool night leaves both neighbours with no holiday episodes. The quarter cap is lifted for Heavy on the holiday date only. Heavy’s holiday night is a marathon: the whole pool back to back from 17:00. If it is longer than the band, it starts early enough to end by 23:00, but never before the day starts. It uses the evening band whatever the placement setting. Each episode is due when the one before it ends, so a marathon longer than the rolling window carries on into the next window, and a window the marathon fills airs the marathon alone. A window never goes empty. Episodes that would start after the date ends do not air that night (a pool longer than a day fills the date).
    • Spacing: the in-season exception to episodeNoRepeat. Honouring the channel’s 7-day episode spacing would cap a nine-episode pool at one a day at every strength. Featured holiday episodes instead rotate evenly through the pool: day d features pool positions d·q … d·q+q−1 (mod pool size, pool in deck order), so an episode returns after at least ⌊pool/q⌋ days, and q is capped so that gap is never less than 2 days (never twice in a day, never on consecutive days). A small pool therefore caps the strength: nine episodes give Light 1 every 9 days, Featured 3 every 3, Heavy 4 every 2. A pool of one airs every other day.
    • Placement (seasonal.placement, default evenings). evenings: the day’s featured episodes are spaced evenly through 17:00–23:00 channel-local (the guide time zone, the same clock the rolling window turns on). anytime: spaced evenly through the whole day. Start times are estimated from programme runtime stretched by the channel’s break density.
    • Out of season a holiday episode of an ordinary series is never benched: it stays in its window’s tile. With anytime it is untouched. With evenings it is kept out of the channel-local evening band. If the clock reaches it inside the band, it is deferred to the first moment outside the band. Holidays the channel has deselected are ordinary episodes.
      • Shuffled and Syndication: the repeat spacing wins over the evening (#1960). Deferring an episode brings every unit behind it, up to the band’s end, one slot forward. The dealer releases a held-back unit exactly at its spacing, so that slot re-aired it sooner than the spacing promises, on any evening, at a rate set by the channel’s deal origin. So an episode first swaps places with one ordinary unit (one with no selected holiday) that airs after the band in the same window. Every unit between keeps its place in the programme count the spacing is promised in. The swap is taken only when the episode then starts outside the band, and both units still rest the dealer’s spacing (in programmes), or no less than their deal gave them: the unit from its last airing, the episode before its own next one. Nor may the swap’s shift in start times carry any other unit past a holiday feature’s start, which would air that unit later. Of the units that qualify, the one with the most slack over its spacing takes the episode’s place. A multi-part story is never split.
      • Failing that, the swap goes the other way (#1971). The episode swaps places with an ordinary unit that starts before 17:00 in the same window. The episode moves earlier, which widens the gap to its own next airing. That gap is what stops most swaps after the band. The unit moves later. This happens only far from a season, where every window the spacing reaches airs its deal: none is in season, in the simulation or in the hand-off (#2001). The swap must also keep the window’s programme count and leave every other unit on its side of the band.
      • When no unit qualifies, the episode is deferred as before, but only when every unit it brings forward still rests the spacing from its last airing, and the episode still rests it before its next airing. Otherwise it airs in place, in the evening. So does an episode the window cannot carry past the band, because the window closes inside it.
      • The checks stay exact. They read the windows around as dealt, without arranging them, and bound how far a neighbour can move what they read. A unit moved earlier is checked against its last airing as dealt, because a neighbour moves an ordinary unit later only by a swap before the band. That swap checked the unit against the earliest its next window can bring its next airing: the first holiday episode that window deals at or after the band ahead of it. An episode moved later leaves a slot of room for each episode its next window could defer from ahead of it. An episode swapped earlier than that room is checked against the latest its last window can air its last airing. That is as dealt if the airing was dealt before the band, otherwise that window’s last programme. The full argument is at swapOut. Near a season, the simulation and the hand-off check what really aired.
      • The cost. Some off-season holiday episodes stay in the evening on these channels. Measured over 30 deal origins in March, these are the holiday episodes dealt into the evening that still air there: 33% on an 80-episode deck in 6-hour windows, 25% in 12-hour and 31% in daily windows, and 17% on a 400-episode deck in daily windows. The dealer rests a holiday episode only a little past its spacing. Moving it after the band brings its next airing too close, and moving it before the band brings its last one too close.
      • In order the dealer promises no spacing, and every episode leaves the band. If the window ends inside the band (a short window), the deferred episodes move, as one run, to just before that band. They go at the latest point where each still starts before 17:00. Whatever does not fit before the band airs at the window’s end: a window wholly inside 17:00–23:00, or one with less time before the band than the run needs.
    • Holiday windows are channel-local dates. Whether a holiday is active, for the title-level boost and bench, the exclusive pass, this feature and the cycle-cache clock signature, is decided by the channel’s date on the guide time zone. It is not decided by the UTC instant, which would end Halloween at 20:00 on Oct 31 in New York.
    • The cycle preview carries the consequence in holidayEpisodes, per selected holiday, open or soonest first: the episodes found, the per-day count and spacing after the day cap, capped (the pool or the cap holds the strength back: fewer a day than it asks for, or not every day), and sameAs (the other strengths that rotate the pool identically; a pool of 5 makes Featured the same as Heavy, and a pool of 1–2 makes all three the same). The channel page can then say what a strength will do, and when a choice changes nothing, without counting anything itself.
    • Where the operator sets it. The channel’s Programming tab (ChannelSeasonal, built on ChannelSeasonalFields in @loomarr/ui) offers Holiday strength (Light / Featured / Heavy, each choice carrying its own plain-language consequence) and Favour evenings only while the mode is the built-in rotation; exclusive and off keep their meaning and show neither. Under Holiday strength one line restates the preview’s holidayEpisodes for the holiday that is on, or next: the episodes found and the resulting per-day count and spacing. When sameAs is non-empty or capped is true the line says so plainly (“at this pool size Featured and Heavy play the same”). The line is the backend’s numbers, never a client-side estimate.
  • mode: "exclusive": the channel is the holiday (a December Hallmark-style channel): only in-window seasonal content airs; out of window the channel runs its offSeason fallback (loop scope without seasonal filter, or go dark — policy field, default loop). A holiday puts the channel in window only when the channel has something for it — a title that fits, or a series with an episode that does (#2030) — so a Halloween channel with every holiday chosen runs its fallback through back-to-school rather than emptying. A series whose episodes cannot be judged (stale editorial evidence) counts as having something, as before.
  • mode: "off": no detection, no bench — for channels where a Halloween Simpsons episode in March is fine.
  • Evaluation uses the reconcile instant’s date on the guide time zone (guide.timezone, the clock the rolling window turns on). The holiday-episode feature above reads the calendar dates of the window it arranges instead. The periodic sweep naturally rolls channels into and out of windows within CHANNEL_RECONCILE_EVERY — seasonality needs no scheduler of its own.

6.5. Curation rules (“play different things at different times, like a real network”)

The policy so far describes ONE deck that Tunarr loops forever — time-agnostic. Real channels are wall-clock-conditional: weekend marathons, holiday programming, day-parts (kids in the morning, drama at night). A curation rule is the unifying abstraction — a (WHEN, WHAT, HOW) triple — and §5 ordering + §6 seasonality both compose into it (seasonality is a (when=holiday-window, what=keyword-match, how=boost) rule).

Seasonal-as-a-rule (the shared-calendar contract). Seasonality (§6) is the archetypal time-conditional rule and it is unified with the rule engine at the calendar layer, not rewritten as a generic rule — a deliberate choice. auto mode does two asymmetric things at once (bench out-of-window seasonal items and boost in-window ones by light duplication) and exclusive mode has an offSeason fallback ladder (loop / dark); a rule’s intersect-only What and ordering-only How cannot express boost-by-duplication or “bench items seasonal for a different holiday” without bloating the rule model. So the seasonal mechanism (applySeasonal) stays intact, and the unification is that the holiday When predicate and the seasonal engine share ONE calendar (schedule.Calendar): When{Holiday:"christmas"} is active exactly when the seasonal engine considers christmas in-window — proven across every day of the year, in every shipped country, by a cross-consistency test, so the two can never silently diverge. In ComputeDesiredAt they compose: a rule’s What narrows the pool first, then seasonal bench/boost runs on the narrowed set (so “a December holiday rule” and seasonal auto reinforce rather than contradict). This keeps the seasonal regression oracle green by construction — the mechanism is untouched; only the calendar is shared.

  • A rule = {Priority, When, What, How, Window}. When is a deterministic, composable predicate (weekend/weekday, day-of-week, an hour range that wraps for late-night, a holiday-calendar id, a date range; all-zero = always-match). What reuses ScopePolicy and only ever narrows the eligible pool (never widens — it can’t admit content the channel’s own scope/audience excluded). How reuses the ordering + separation vocabulary plus noBreaks and a marathon sugar. Window is an optional per-rule override of the channel window (below).
  • Overlap resolution is first-match by (Priority desc, then list order) — NOT a merge (merging two Whats is unpredictable and can’t be previewed). When several rules match a moment (“Saturday morning in December”), the highest-priority one wins; the natural default ordering mirrors a real programmer (holiday > weekend/daypart > base). When no rule matches, the channel falls through to its base whole-policy behavior. Resolution is visible in the cycle preview (§8, ?at=<time>), so which rule is active at a given moment is answerable by looking, never a mystery.
  • Presets, not cron. Users and the LLM compose from a closed, named vocabulary — WHEN: weekend/weekday, mornings/primetime/late-night, holiday:christmas; WHAT: series:X, genre:kids, holiday-matched, all; HOW: marathon, syndication, shuffle, feature. Every preset lowers to primitives that already exist (marathon = sequential + no breaks + unbounded block; holiday-matched = the §6 keyword engine; syndication = the §5 deck), so the engine is a composition + time-routing layer, not new scheduling math.
  • Rolling window — a ROTATING slice of the catalog, not a fixed prefix. A channel materializes only ~Window of runtime (default 24h, per-channel/-rule overridable, global default sched.window_hours) rather than the whole run — so a channel schedules a manageable timeframe and is curated over time. The window keeps a rotating slice of the ordered deck whose start advances by the coarse window index (floor(now/window)): window 0 airs the first ~Window of runtime, window 1 continues where it left off, and the slice wraps past the end back to the deck head. A channel with 30h of films and a 24h window airs [film k … end, start … ] each day with k advancing daily, so over a full cycle every title airs — the coverage invariant: across ceil(totalRuntime / window) consecutive windows, no program is starved (the whole catalog rotates through). This is what makes “continuously updated and curated within the window” true — without it, keeping only the deck prefix would loop the same head every window and permanently starve the tail (the bug this fixes). New titles (backfill / a manual add) join the deck and enter the rotation on the window that reaches them — the auto-updating half is free. Idempotent + thrash-free: the slice offset is a pure function of the window index, so it is identical within a window (two reconciles → byte-identical desired → no Tunarr re-push) and advances exactly once at the boundary (one re-push, the next slice). The slice operates on the collapsed deck (multi-part/franchise super-slots, §5), so the window seam never splits a two-parter or a franchise. Window: 0 = the whole run (the “full binge” sentinel; a marathon rule sets it — no rotation, plays everything). A pool smaller than one window airs whole every window (nothing to rotate, nothing starved). The slice is floored to at least one program so a channel is never dark. Passes: a shuffled or syndicated catalog is dealt afresh each time the window wraps it (#1676). One trip of the window around the catalog is a pass; pass p is dealt under seed XOR p (the seed is the channel’s own, §5), so a pass is a new permutation, not a replay of the one before, and still a pure function of its inputs. sequential keeps one deck for every pass — its order is the promise. Passes are numbered from the channel’s origin (created_at, else its playout anchor, else a stable value derived from the channel id), not from 1970, so a channel’s pass number is its age in passes: a few hundred in a year, never thousands. The seam between two passes is repaired: every unit airs at least a repeat spacing after it last aired — the episode/film no-repeat window, capped at a third of the pool’s runtime (a pool shorter than the spacing can never honour it; §7 owns that shortfall) — with floors that win over that cap, none longer than the pool itself. The true guarantee: a unit never airs twice in a row (the spacing is at least two longest units); a pool wider than a window rests every unit more than a window (a window and a unit at least, two windows and a unit once the pool is three windows wide, since a window’s last programme runs past its close and two consecutive windows span up to two windows and a unit), so a unit never airs twice in one window and the next window starts exactly where this one stopped. A shorter rest would let a unit from the end of one pass land in the same window again: the window skips it and reads past its stride, and the next window re-airs what it pulled in (27 one-hour films in a 24 h window re-aired units 2–3 h apart). A pool barely wider than a window (under a window and a unit of slack) is pinned close to its old order: that is the price of never repeating inside a window. A unit not yet allowed is held back and goes out the moment the deck reaches its release time. A repair moves a unit at most 2·spacing + 2·longest unit into the deck. When that stops short of the tail the next seam reads (a pool wider than a window holding three spacings), the repaired tail is the dealt tail, so a pass needs only its own deal and its predecessor’s: exact, at any age. A pool of one to six windows (spacing raised to a window or two) is pushed into that tail, so each pass is repaired against the deck that really aired, walked pass by pass (memoised per pool/policy/seed/window; a lineup edit is a different pool, so it restarts the walk). A deal costs 5–22 ms for a multi-series pool, so the walk is bounded in deals: at most 2048 / pool size passes (16 to 2048, a multiple of 16), starting at the latest multiple of that bound at or before the wanted pass; a 6-year-old channel with a 60-episode pool walks in ~0.17 s cold (the warm-up below included), once per process. The anchor’s seam is exact too (#1965): the walk deals a warm-up of about twice spacing / slack passes (slack: the pool’s runtime beyond the spacing) ahead of the anchor, and a walk from any start forgets it within that, so the anchor is repaired against the deck that really aired. It used to be repaired against its predecessor as dealt, and on 80 episodes in a 24 h window an episode aired back to back on one channel origin in five. A pool whose slack is shorter than its shortest unit is pinned: every pass replays pass 0, exactly, with no walk. A catalog that fits inside one window has no ring to wrap, so it used to air the same deck in the same order every window; there the window is the pass, dealt afresh and repaired against the previous window as it aired: playout loops the deck until the window closes (elapsed % total), so the units that closed it are wherever the loop stopped, not the deck’s end, and the seam is repaired against that looped tail. Since any part of the deck can be that tail, such a pool is always walked pass by pass. Recency does not order such a deck: it airs every unit every window, so oldest-aired-first is just yesterday’s order, a replay that survived every window once anyone watched (#1676, reversing #1694’s “recency still orders a fitting deck”). The window’s order is fixed when it opens and does not move as viewing is recorded (#1674).
  • Authorship is hybrid (§8 boundary intact). The LLM proposes a starter rule set from intent (“Star Trek with weekend TNG marathons and Christmas episodes”) — from the closed preset vocabulary, grounded + clamped (unknown tokens dropped, window clamped to [1h,168h], daypart audience ceilings stricter-only — a rule may never raise a kids channel’s ceiling, §4). The user refines rules in the channel “Programming rules” editor (chips, drag-to-priority). The LLM still only proposes rule VALUES; deterministic code evaluates When and enforces — the model never orders episodes.
  • No new scheduler. Rules evaluate against the container wall-clock at reconcile time; periodic channel maintenance (§main-doc) already re-runs the pure lineup builder with a fresh now, so it is the refill loop — a rule/window boundary simply produces a different desired lineup on the next sweep. Because the desired lineup stays a pure function of (seed, coarse-now, policy), reconcile idempotency holds within a slice.
  • Drift vs. rotation (a correctness rule). A rule swapping the active pool (kids AM → drama PM) legitimately changes which programs air — this is NOT drift. Drift detection (§9 slot revalidation) therefore compares against the eligible set (what the library can currently supply), not the selected set, so “the library lost a title” (real drift → StatusDrifted) is cleanly separated from “the active rule rotated a title out” (normal, silent).
  • Backward compatible. A channel with no rules and no window (Rules==nil ∧ Window==0) is byte-identical to today’s behavior; existing channels are unaffected until a rule or window is set.
  • Rule WHAT remains entry-level. A generic holiday-matched or genre WHAT filter still narrows series/movies. Per-episode holiday precision is activated only by the approved series entry’s episodeSelection policy, which has explicit holiday ids and episode metadata; it is not inferred from an arbitrary rule at reconcile time.

6.6. The preset lowering table (the closed authoring vocabulary)

The LLM and the UI author rules by composing tokens from a closed vocabulary; deterministic code lowers each token to concrete SchedulingRule fields. The model never emits a raw WhenPredicate or hour range — that would be the model doing scheduling math (§8 boundary violation, unvalidatable). It emits {when, what, how, priority?} token strings; groundPolicy lowers them, drops unknown tokens, and clamps. This is the exhaustive v1 table.

WHEN tokens → WhenPredicate (broadcast-standard dayparts, Eastern-style boundaries; evaluated against the container wall-clock):

tokenpredicatedefault priority
weekendSat–Sun20
weekdayMon–Fri20
mornings / early-morninghours 6–1030
daytimehours 10–1730
primetimehours 20–2340
late-nighthours 23–2 (wraps)40
overnight / graveyardhours 2–640
holiday:<id>the §6 calendar window for <id> in the household’s country (christmas/halloween/easter/…; the vocabulary offers only the holidays the country keeps, and one it doesn’t never matches)60
weekend-mornings etc.AND of the two (weekend ∧ mornings)max of the two + 5

Priorities encode a real programmer’s precedence: holiday (60) > daypart-hours (30–40) > weekend/weekday (20) > base (0). A token with no match falls through to the base policy. Ties break by list order (§6.5).

WHAT tokens → *ScopePolicy (intersect-only, never widens; nil = inherit channel scope):

tokenscope
allnil (no extra narrowing — the base)
series:<key>Series: [<key>] (intersected with the channel’s grounded picks; an ungrounded key is dropped)
genre:<name>Genres.Include: [<name>]
genre-not:<name>Genres.Exclude: [<name>]
kids / familyGenres.Include kid-safe genres and a stricter-only audience clamp (below)
holiday-matchedthe §6 seasonal keyword filter (in-window seasonal items only)
era:<from>-<to>Era: {from,to} (clamped)

HOW tokens → RuleOrdering + Window:

tokenorderingseparationbreakswindow
syndicationOrderSyndication (the §5 deck)inheritinheritinherit
shuffleOrderShuffleinheritinheritinherit
marathonOrderSequentialBlockMax: 0 (unbounded — binge one show)NoBreaks: trueWindowFull (don’t truncate a binge)
featureinheritinheritinheritinherit + a light seasonal-style boost (future)

Every token lowers to primitives that already exist — nothing here is new scheduling math. marathon = the three fields above (all present since Phase 1); holiday-matched = the §6 keyword engine; syndication = the §5 deck.

Grounding + clamps (§8 / §4, in groundPolicy) — the model proposes, deterministic code enforces:

  • Unknown token → dropped (never a raw predicate). A rule that loses its WHEN/WHAT/HOW to drops degrades to the base policy — same failure contract as a dropped ordering.
  • Window clamp: any per-rule window is clamped to [1h, 168h] (except the marathon/WindowFull sentinel).
  • Daypart audience ceiling is stricter-only (a §4 prime directive). A kids/family WHAT may only tighten the channel’s ceiling (e.g. TV-14 channel → TV-PG mornings), never raise it — a rule can never make a kids channel show adult content. Enforced at BOTH grounding (clamp the lowered ceiling to ≤ the channel ceiling) and enforcement (the §4 fail-closed gate is never bypassed by a rule). Defense in depth.
  • Series intersection: a series:<key> WHAT is intersected with the channel’s actually-grounded picks, so a rule can’t scope to a series that never surfaced.

7. The relaxation ladder (constraints degrade predictably, never silently)

When the eligible pool can’t satisfy the policy (small library ∩ tight scope ∩ long no-repeat window), each guard the placed cycle breaches relaxes on its own, to the widest value the pool can hold, and every applied relaxation is recorded on the channel and surfaced in the UI (“policy relaxed: repeat window 7d → 3d 4h”) (#4140 decision 3):

  1. episodeNoRepeat / movieNoRepeat. An item airs once per loop of the cycle, so a window longer than the cycle’s program runtime relaxes to that runtime, to the minute. Episodes and films are judged apart: each window relaxes only when the pool holds that kind, and a film shortfall never shortens the episode window.
  2. seriesMinGap. Relaxes only when the placed cycle breaches it, to the widest gap a placement holds, searched to the minute. Zero only when nothing wider holds.
  3. blockMax. Rises only when the placed cycle breaches it, to the shortest run a placement holds. Unbounded only when nothing shorter than the largest show’s whole run holds.

A shortfall in one guard never touches another: a cycle shorter than the no-repeat window keeps the series gap, and a series-gap breach keeps the no-repeat windows. The gap is settled before the run length, because a run of two always breaches a gap.

Never relaxed, ever: audience and scope — explicit series/seasons and the dates, era-shaped or not. A channel short of titles stays inside its line and says so; growth (#4140 step 2) is what widens a pool. A too-small kids’ pool becomes a filler-heavy kids’ channel — it does not become a less-kids channel. Mirrors the pod fallback ladder’s philosophy: degrade quality, never safety or identity.

8. Pipeline placement & proposal surface

  • Suggester (§8): output contract gains policy (schema above), grounded like everything else; templates ship pre-filled policies (”90s Saturday Morning” carries TV-Y7 + era + genres out of the box); intent-hint copy teaches the constraint vocabulary.
  • Proposal review + channel editor (§12): policy renders as editable chips (ceiling, seasons, era, ordering, seasonal mode) + the exclusion report (§4) + a cycle preview (§8.1 GET …/cycle?at= — first N slots with the active-rule attribution) so “did old-school bind?” and “what airs Saturday 9am?” are answerable by looking. Every series row also names its proposal-owned episode-selection mode before approval: all episodes, curated highlights, or the explicit holiday scope. The review explains the selector; it does not let the client choose episode identities or bypass the deterministic binder.
    • ⚠ The exclusion report reaches the CHANNEL EDITOR only; proposal review still does not show it. Both preview endpoints (GET …/cycle and POST …/programming/preview) carry excluded — counts plus a per-item reason — and the cycle-preview panel renders it under the schedule. This half of the sentence was aspirational for as long as the type existed: ComputeDesiredAt filled the report on every reconcile and every caller discarded it, so a title the ceiling refused was invisible product-wide, and diagnosing one meant querying the media server by hand. Reconcile still discards its copy of the per-episode report — the preview recomputes the identical report from the same pure builder. Both remaining gaps are real and named rather than implied.
    • A lineup title that cannot air is reported on the channel (#4140). Each reconcile writes policy.unairable: every lineup title that put no programme into the cycle, with why — not_in_library, no_episodes_in_seasons, over_ceiling, unrated, out_of_scope or no_episodes_selected. It is reconcile-owned like applied (recomputed every reconcile, ignored on write, left out of what tells an edit from a library change) and the channel’s Info page shows it to admins. A title the active rule or the seasonal bench rests is not on it: it airs at its time. The same chip surface is the per-channel rules editor (§8.1) on the channel page (§7 PATCH .../{id} writes policy_json); omitted chips inherit the built-in default (§9), and audience + explicit scope are shown as never-relaxed safety fields.
  • Filler is part of the channel editor too (§10): policy.filler (the FillerSelection) is edited on the channel page alongside the rules chips — theme criteria (era/audience/category/kinds) + pinned/excluded clips — with a live pod sandbox (POST …/pods/preview) that re-assembles the actual break against the unsaved draft before Apply. It also rides policy_json. The first approval of a generated Channel seeds its era from the grounded scope.dates and derives a conservative audience from the approved rating ceiling (TV-Y/TV-Y7 → kids, G/TV-G/PG/TV-PG → family, otherwise general). Program genres never become filler product categories, and missing intent never invents late-night eligibility. This is a one-time ownership handoff: a present operator selection, including an explicitly empty one, is sticky across refine, re-curation, and reconcile.
  • Lineup builder (§9): hard filters → eligible pool → seeded constraint-aware slotting (greedy with backtracking is sufficient at envelope scale) → relaxation ladder on failure → pods → push. The periodic sweep re-evaluates policy (seasonal windows roll, library grows, relaxations un-relax when the pool recovers).

8.1. The cycle-preview endpoint & the rules editor (making the engine legible + editable)

Two surfaces make curation rules authorable and their resolution visible — the whole point of first-match-by-priority is that it must never be a mystery.

GET /v1/channels/{id}/cycle?at=<rfc3339> — the time-travel preview (read). Any authenticated user; a pure, side-effect-free look at what would air at a chosen wall-clock. It runs the identical ComputeDesiredAt the reconciler runs — same channel, same approved lineup, same live availability, same policy — only with now set to at (default: the server’s clock). Preview and reality therefore cannot disagree, exactly as the pod preview (§10) can’t drift from the assembled pod: there is one code path, called twice. The response is:

  • at — the resolved wall-clock the preview was computed for (echoed, so a client sees which moment it’s looking at).
  • activeRule — the rule pickRule selected for at: { id, label, priority, matched }. matched:false (with a synthesized label:"Base policy") means no rule matched and the channel fell through to its base whole-policy behavior. This is the attribution that makes overlap resolution answerable: “at Saturday 9am, the Weekend TNG marathon rule (priority 20) is active.” It is derived from the same pickRule call the engine makes — never a re-implementation.
  • window — the resolved rolling-window horizon for at (rule > channel > global default; 0/null = whole run), so the preview explains why it shows ~24h of slots and not 800.
  • slots — the first N program/pending/break slots of the resolved cycle (N capped, default 50), each { kind, title, key, seriesTitle, part } — enough to see intermixing, marathons, and franchise/two-parter adjacency at a glance. Filler break gaps render as kind:"break" (Tunarr owns what plays into them; the preview shows the gap, not the clip).
  • trace — the bounded ScheduleTrace emitted by that same ComputeDesiredAt call (§8.4), including hard-filter, availability, episode-selection, window, and placement facts. It is not reconstructed from slots or from the originating Proposal.

The preview is read-only and never touches Tunarr or the store — it is ComputeDesiredAt on already-loaded state. at in the past or far future is legal (that’s the feature — “what airs next Christmas morning?”); an unparseable at is a 400.

The “Programming rules” editor (PATCH /v1/channels/{id} → policy_json, admin) — authoring. The channel page’s Programming surface (design.md §12) renders policy.rules as an ordered list of rule chips, each showing its WHEN/WHAT/HOW tokens and priority. Authoring is token-based, never raw predicates — the same closed vocabulary the LLM uses (§6.6). The vocabulary + lowering table is BE-authoritative, served by GET /v1/programming/vocabulary (the WHEN/WHAT/HOW presets and how each lowers to SchedulingRule fields). The editor renders from it and the suggester’s groundRules lowers with it — one source, so hand-authored and LLM-authored rules are byte-identical by construction (this closes the drift hazard of the FE re-implementing the §6.6 table). The BE re-validates on write (unknown tokens dropped, window clamped, audience stricter-only — enforced on every write path, not just the LLM’s). Each rule carries a source (llm or operator) stamped at authoring time — the provenance a refresh proposal merges on (§8.2): a refine replaces the llm rules and preserves the operator ones. Priority is drag-to-reorder (list order is priority; higher = higher). audience and explicit scope remain never-relaxed safety fields, shown but not loosenable by a rule (§4, §7). Every save auto-reconciles (no rebuild).

POST /v1/channels/{id}/programming/preview — the whole-definition draft preview (admin authoring). The cycle preview above (GET …/cycle) and the pod preview (GET …/pods, §10) each preview saved state; this generalizes both to an unsaved draft — body {lineup?, policy?}, returns the shared shape {at, activeRule, window, slots, trace, pods} without persisting. It runs the same ComputeDesiredAt + pod assembler as reconcile (so a drafted lineup + rules + filler edit preview exactly what will air once applied), and is the call the Programming surface’s scheduling-rules draft uses while editing (design.md §12 — the third review-before-apply surface, and the only block of that page that drafts; scope/ordering/auto-curate stay seamless because their edits are self-contained). ⚠ This sentence previously read “the one call the Programming surface uses while editing”, which asserted a whole-page draft §12 did not sanction and the implementation never built — a companion doc contradicting the design doc, which AGENTS.md resolves in the design doc’s favour. It does not replace the read paths: GET …/cycle stays the any-authenticated verification pane and GET …/pods the saved-pool read — the change is one shared response schema, not deleting the GETs. The preview shows play order, not wall-clock. Overview airtimes come from the backend actually streaming the channel: Tunarr’s guide for Tunarr-backed channels and Loomarr’s internal timeline for internal channels.

POST /v1/channels/{id}/programming/changes — the upcoming slots a draft changes (#1877). The single-point preview answers “what airs at T”; this answers “where does this edit change the schedule”. Same body, validation and authorization as programming/preview; query from (default now) and horizonHours (default the channel’s rolling window, 24h when unbounded, at most 168). It forecasts both sides with one walk: the saved channel and the draft, from the same instant, the same playout anchor and the same engine (Engine.ScheduleDiffDraft). The walk re-arranges where the channel would — at each rolling-window turn (carry-over for internal playout, a cut on the boundary for Tunarr, as the guide forecasts them) and at each instant the active rule or holiday set changes, because ComputeDesiredAt arranges a cycle for the rule active at its instant; without the rule boundaries a Sunday-evening rule would never appear in a forecast whose windows open at midnight. Each arrangement is PreviewPlannedChannel, memoised on ClockSignature + window index. Because an untouched slot is produced by identical calls on both sides it compares equal, so the response lists only the changes — {fromMs, toMs, compared, count, truncated, changes[{startMs, endMs, before?, after?}]}, each side {kind, title, series?, key, season?, episode?, startMs, stopMs, rule}, capped at 100 rows with count the true total. The two sides are compared at every programme start on either side; content identity is kind + key + title + season/episode, so a programme cut at a rule boundary on one side is unchanged while both sides air it. It deliberately compares two forecasts rather than the draft against the accepted (persisted) cycle: a stale accepted cycle would otherwise surface as changes the edit did not make. With carry-over the first epoch is playout.WindowTurn over the accepted cycle, so a diff opened while the previous window’s crossing programme is still on air starts from what the encoder airs; instants are evaluated in the engine clock’s location, as reconcile evaluates rule hours. The two sides run concurrently; a 7-day diff of a 200-title shuffled channel with a nightly rule measures ~120–145 ms (BenchmarkScheduleDiff_SevenDays), so it stays in the request path.

8.2. Self-updating channels (scheduled re-curation)

A channel built from an intent shouldn’t be frozen at build time — as the library grows and new titles land, the channel should keep curating itself toward its original intent. Re-curation is that loop: on a schedule, a channel re-evaluates its intent against the current library and evolves its lineup — preferring what’s already there, weighting net-new acquisitions by quality + intent fit, and never bypassing the approval gate.

It is a composition over existing parts, not a new engine. The suggester already (a) re-runs against a stored intent + the current lineup as context (the refine path, §7), (b) splits picks into in-library (free, instant) vs acquisition (must request), (c) scores theme-first (§8.1 suggester), and (d) re-validates acquisitions vs TMDB. Re-curation just schedules a refine and lets the results flow through the same approve → bind → reconcile pipeline. The genuinely new pieces are a scheduled job, a per-channel opt-in, and a channel-scoped auto-approve grant.

  • A scheduled job channel-recurate (default weekly, job.recurate.schedule; Run-now-triggerable like every §18.1 job; LLM-cost-bearing so infrequent). For each live, intent-backed, auto-curate-opted-in channel (IntentRef != "" ∧ AutoCurate ∧ status live/building; hand-made / paused / detached / opted-out channels are skipped) it triggers a refresh refine — a new job seeded from the intent the channel owns (channels.intent_json) + its current lineup, with no operator RefineText (the “change” is simply “re-evaluate against what’s in the library now”). A channel with no stored intent is skipped with a logged reason. The new job names the channel (proposal_jobs.channel_id), has no requester, and is durably marked kind=recurate; the worker uses that server-owned marker to select the channel-scoped grant. It skips the requester’s ordinary auto-approve grant for this run, and ordinary/manual refine jobs never reach the auto-curate grant. Without that discriminator, a requester grant could bypass the channel quality/cap thresholds, while a human refine on an opted-in channel could be silently treated as unattended work. Discovery-feedback scope follows the same durable authority: immediately before generation the worker resolves the Channel the trusted claimed Job names (proposal_jobs.channel_id) and attaches that Channel id only to the in-memory Intent. The serializer never persists this execution field. Missing, removed, detached, unreadable or empty ownership fails the Attempt before catalog or provider access; fresh suggestions and manual refines use household feedback only. An admin may name a Channel when recording an editorial feedback event, but that event field is not execution authority.

  • Library-aware + intent-weighted. The fresh proposal already classifies picks. Re-curation leans on it: an in-library title that fits the intent is added to the lineup immediately (already available → airs next rotation, zero acquisition, no approval needed — it’s a lineup extension, like a manual add). A net-new (not-in-library) title is only requested if its intent-fit score clears a quality bar (recurate.min_score) and the channel isn’t at its title cap (recurate.max_titles); candidates are ranked by score and the top ones taken. Both knobs are global settings (env > db > default) with an optional per-channel override on the opt-in, so a channel can be more or less permissive than the fleet default.

  • Additive lineup binding — auto-curate ADDS, humans REPLACE. This split lives in the ChannelBinder, keyed on the proposal’s approvedBy audit field. A human-in-the-loop approval (manual approve, or a manual refine the operator drove) replaces the lineup — a person decided, including to remove titles. Scheduled auto-curate runs unattended, so it is non-destructive: it UNIONS the refreshed proposal’s picks onto the channel’s existing lineup and keeps every still-available title the refresh merely didn’t re-pick (an LLM is stochastic; omission is not a decision to remove). Without this, weekly re-curation would churn — silently dropping good, available, on-theme titles nobody chose to drop. Conservative pruning is the one exception: auto-curate drops an existing title only when it is clearly off-intent — it has genuinely left the library (state unavailable), or the intent’s mustExclude names it. A title that is still available (or an acquisition still in flight — wanted/requested/downloading) is never dropped by re-curation. Every drop is logged. So re-curation grows a channel toward its intent and prunes only the clearly-wrong; a refresh that finds nothing better leaves the channel exactly as it was.

  • Retirement at the cap — the turnstile (§8.2a). Additive binding plus a title cap has an end state nobody chose: a channel grows to recurate.max_titles and then freezes permanently. room reaches 0, every future candidate is dropped, and re-curation keeps running, keeps spending tokens, and can never change anything again. Observed on the dev “1980s Action Heroes”: 25 → 27 → 30 → 34 titles against a cap of 40, with nothing ever leaving. Growing and frozen were the only two states; neither is rotation.

    So a channel above its rotation target (¾ of the cap) trades rather than only grows: a genuinely better candidate retires the weakest retirable title even while free slots remain, and at the cap it does so instead of being discarded. Retiring only at 100% was itself the wrong trigger — it made the lineup a ratchet, appending every run and dropping nothing until the channel froze, so a lineup curated for weeks still led with its original picks (“why do I still see the same old movies”). A real station retires a film once it has had its run; it does not wait until the shelf is full. Below the target nothing is retired at all — a young channel should fill up, not churn. Confidence is the criterion — the same per-title score the quality bar reads, which is only meaningful now that the prompt calibrates it (§8.3). The cap becomes a turnstile rather than a wall.

    ⚠ Nothing currently scheduled may be retired. A title in the channel’s Desired slots is airing in the current window — someone may be planning to watch it today, and pulling it out from under them is worse than a stale channel. ch.Desired is already persisted per channel, so the guard costs no new dependency: the retirable set is lineup − scheduled. Measured on the same channel: 34 in the lineup, 15 scheduled (protected), 19 retirable. A retirement that cannot find an unscheduled, weaker title simply does not happen — the newcomer is dropped over-cap exactly as before, which is the safe direction.

    Retirement is otherwise bounded by the same rules as everything else here: it happens only for a channel that opted into AutoCurate, only when the incoming candidate’s confidence exceeds the retiring title’s (never a tie — a coin-flip churn is the failure mode additive binding exists to prevent), and every retirement is logged with both titles and both scores. This narrows §8.2’s “conservative pruning” rather than replacing it: the unavailable / mustExclude drops still apply on every run, cap or no cap.

    ⚠ recurate DECIDES a retirement; the binder APPLIES it. One subsystem writes a channel’s lineup. The turnstile records its rotate-out keys on the proposal (Proposal.Retired), and the binder consumes them as a third ApplyOpts.Drop signal alongside unavailable and mustExclude — so every lineup write still goes through the single schedule.ApplyLineup primitive §9 requires. This is a correction: recurate originally trimmed ch.Lineup and persisted the channel itself, moments before the binder’s additive union ran over the same field. Two writers, sequenced only by a code comment explaining that the trim had to land first or the union would put every retired title straight back — an ordering nothing could check and a new caller could not discover. Retirement is a decision, unlike the other two drop signals, which are observations: a retired title is usually still perfectly available, so the availability test would say “keep” and the swap would silently never happen. That is why it is checked first and needs no store read.

  • The approval gate is non-negotiable (prime directive #3). A net-new acquisition NEVER becomes a wanted title by a direct write. It routes through the one accept.Approver implementation — the same gate a human admin uses. Per the locked decision, unattended additions are a per-channel AutoCurate opt-in (not on by default): when set, a channel-scoped auto-approve grant approves the refreshed proposal because the channel opted in, recording approvedBy: "auto-curate" for the audit trail, still bounded by the quality bar + title cap. A channel that hasn’t opted in still gets re-curation proposals in the approval queue for an admin to act on — re-curation surfaces “N new titles fit this channel,” it just doesn’t auto-request them. Auto-curate is a gated convenience, never a gate bypass.

  • One approval path (no drift). A constructed Approver is the sole public seam used by the manual handler, the per-user auto-approve grant, and auto-curate. It applies the edit and audit stamp, asks the binder to derive the channel from that exact proposal, and commits the proposal + insert-only title records + intent-bound channel as one compare-and-swap transaction. The binder’s planning half performs no write; its post-commit half owns only derived codec work and the immediate external reconcile. This makes an approved proposal without its local channel unrepresentable and leaves the due building channel as the durable retry when Tunarr is unavailable. The policy refresh is not a wholesale overwrite: it goes through the single merge that (a) skips any proposal-owned field the operator has marked operator-set (§2.1 stickiness), (b) keeps filler/window/autoCurate always, and (c) merges rules by provenance (replace llm, keep operator).

    Every channel mutation participates in one revision protocol. The persisted channel carries a monotonic row revision independent of its display timestamp. A new row begins at revision 1; a full replacement must name the revision it read and atomically advances it, while a stale save changes nothing. Claims and targeted derived writes advance the same counter, so a stale full snapshot cannot restore an old lease, codec, Tunarr id, clip override, desired lineup, or policy. Approval treats a stale channel as a rolled-back/replan result: proposal, titles, and channel still commit together. The same transaction also rejects a candidate when that job already has an approved proposal created at the same persisted second or later: channel CAS protects a stale channel snapshot, but this second guard prevents an older decision from reading a newer snapshot and then validly CAS-ing the older lineup over it. Same-second proposal order is unknowable at the stored timestamp precision, so the gate fails closed rather than guessing. Reconcile likewise reloads and recomputes after a stale final write; its Tunarr checkpoint is a targeted compare-and-swap of the server id and number actually used, so an auto-renumber survives a later lineup failure without overwriting a concurrent operator edit. If two Postgres replicas create before either checkpoint wins, the loser removes its unattached remote id after the durable row proves that a different id won; process-local channel locks are not treated as replica coordination. The operator PATCH carries the revision shown to the editor and returns 409 rather than replaying a stale whole-lineup/policy replacement onto a state the operator never saw. This protocol is adopted by every channel-row writer; a writer that does not advance or validate the revision reintroduces the lost-update bug.

  • Cost-guarded + idempotent. A channel whose intent-hash + lineup are unchanged since its last re-curation is skipped (the suggester’s intent-hash cache), so a weekly run that finds nothing new makes no LLM call and no proposal. A re-curation that produces an identical proposal is a no-op end to end (same bind, no reconcile push — the §6.5 idempotency).

The safety posture mirrors the rest of §4/§8: re-curation can loosen content over time (add titles) but never weakens a gate — the audience ceiling (§4, and the kids-only default), the approval gate, and the per-channel opt-in all still hold. It grows a channel toward its intent; it can’t turn a kids channel adult or spend acquisitions a human never authorized.

8.2.1. Growth from the line the seeds draw (#4140 step 2, #4333)

#4140 replaces re-curation with deterministic growth, in internal/channels/growth. The line, the fit, the target and the plan are pure. growth.Fill is the nightly channel-growth job (job.growth.schedule, 00:05 by default), and it uses no model.

  • The seeds draw the line (growth.DrawLine). Every lineup entry is a seed until growth adds titles of its own. A seed with nothing airable is ignored. One airable seed, or none, fixes the line: a single-show channel never grows. Seeds that all share one franchise make the line that franchise. Otherwise the line has four parts:

    • Kinds: every kind held by at least a quarter of the seeds and by at least two.
    • Years: the seeds’ years split into runs wherever neighbours are more than 2 × margin + 1 apart. The line spans the run holding more than half of them, or all of them when no run does, plus margin (3) either side.
    • Genres: those at least half the seeds carry.
    • Rating: no higher than the highest rating among the seeds that are not odd. NC-17 counts as above R and TV-MA here, though the audience ladder ranks them together: seeds that stop at R don’t make an NC-17 channel.

    A seed outside the kinds, years or genres is odd. It keeps airing, is listed, and does not widen the line.

  • A title sits against the line (Line.Classify) as one of four fits:

    • clear when it carries at least bar (0.5) of the line’s genres, and at least bar of its own genres are the line’s (a crime thriller tagged drama is not a drama, and a clear fit airs before the model sees it);
    • unclear when it carries fewer, or has no year;
    • unrated, which never joins by itself (decision 29);
    • outside, with the reason.

    The channel’s stored scope and ceiling are applied by the scheduler’s filter first, so the line only narrows them.

  • The target (growth.TargetFor) has three parts:

    • Episodes: a week of the channel’s series airtime without a repeat.
    • Shows: ⌈1 / maxShowShare⌉ (0.15 → 7), so that none dominates a day.
    • Films: a month’s rest for every film (decision 4), sized to the films’ share of the airtime.

    A single-show channel has no target.

  • Measured before anything ships. go run ./project/evidence/curation-1670/report -db <copy> -growth prints, per channel:

    • the line;
    • the clear, unclear, unrated and outside counts in the library;
    • the target;
    • the shortfall after the clear fits, and after the unclear fits too.

    It also prints a sweep of the bar. On the install (2026-11-15) no series channel is short of episodes; three are short of shows. The maintainer chose margin 3, bar 0.5 and show share 0.15 from these numbers (#4333).

  • The plan (growth.Plan) adds clear fits first, the closest to the line first: genre share, then distance in years from the line’s middle, then key. It stops at the target for each kind. A title the model judged does not fit never joins. An unclear fit joins once the model judged it fits. On an install with no model, nothing will ever review it, so it joins while the channel is still short (decision 8). A verdict counts only against the line it was given for (Line.Words); when the line changes, the title is asked again.

  • The model’s background review (growth.Review, the channel-growth-review job, every 5 minutes by default, decisions 32 and 33):

    • What it asks about, each run: at most four titles. First the titles growth already added (they are airing), then the unclear fits the plan would take if each were accepted.
    • The question: the channel’s name, its line in words, a few of its own titles, and the candidate. The answer is a fixed choice, fits or does_not_fit, with a reason of a few words.
    • What a verdict does: it is kept in growth_reviews per channel and title, with the line it was given against. A grown title judged not to fit is taken off through edit.Service, which declines it. A person putting it back by hand is the undo: a title added by hand is a seed, and the review never asks about seeds.
    • When it waits: while a person waits on the model (llm.InteractiveGate), and at the day’s AI spending cap. A hosted model’s questions reserve in the filler inference ledger under filler.defects.judge_daily_cents, the one daily cap for filler and programme work (#3838 decision 19). A self-hosted model costs nothing and never waits on the cap.
    • An answer outside the choices leaves the title unjudged, and a later run asks again. A fixed line adds nothing, and neither does a declined title.
  • The nightly fill (growth.Fill) reads the library once and then goes through each channel:

    • Which channels: those that reconcile, grow (not kept as they are) and were made from a request. A channel made by hand waits for a writer of its own, because approval binds only to a channel made from a request. A channel with a proposal in flight waits for the next night.
    • Seeds: the lineup entries with no batch (LineupEntry.Grown empty). Titles a batch added are carried towards the target but never draw the line.
    • Candidates: the library’s playable series and films, keyed by TVDB for a series and TMDB otherwise. The channel’s stored scope and ceiling (schedule.Admitted) apply first. On an exclusive holiday channel, a candidate must also fit one of the channel’s holidays (schedule.FitsHolidayChannel, the in-season filter’s own judgment). Its genres are only its mood: a Christmas channel scoped to Comedy must not take every comedy. The report applies the same filters, so its counts are what the fill would add. On the install it would add 15 titles to the holiday channel (not about 290 comedies), and that channel stays short by 276 films.
    • Writing: the picks become one proposal (Proposal.Growth holds the batch, growth-YYYY-MM-DD). It is recorded against the channel (Workflow.RecordForChannel) and approved with accept.AutoCuratedBy, so the binder unions it onto the lineup and stamps each entry with the batch. A growth batch never restates the channel’s request; the channel keeps its own, or none.
  • Undo is taking it off. Any edit that takes a grown title off the lineup adds it to GrowthPolicy.Declined (edit.Service, ChannelPolicy.WithRemovedGrowthDeclined). It never rejoins by itself, and a person can still add it back by hand. The list holds 1000 refusals and forgets the oldest first. GrowthPolicy.Keep stops growth for a channel, and a policy PATCH that leaves growth out keeps both.

8.3. Adjacency candidates (a deterministic second corpus)

Re-curation (§8.2) asks the LLM “what else fits this intent?”. That is the right question for interpreting an intent (“gritty 80s action, nothing campy”) and a weak one for finding adjacency inside an already-established set — the model free-associates from the intent text, not from the channel’s actual contents, and it costs a token spend to do it.

A channel’s own lineup is a query. TMDB’s /{movie,tv}/{id}/recommendations is a behavioural graph (“people who watched this also watched…”), and walking it from every title a channel already has, then counting consensus, yields candidates that are on-theme by construction. This is §1’s prime principle applied to discovery: the LLM extracts intent, deterministic code finds neighbours.

  • Consensus is the signal, not any single edge. One film’s recommendations are noisy; a title recommended by several of the channel’s films is reliably on-theme. Rank by that count. Measured against the dev “1980s Action Heroes” (25 films): the consensus head was Terminator 2, Mad Max, Death Race 2000, Demolition Man, Missing in Action, Romancing the Stone — including two obvious holes (the channel had Mad Max 2 + Beyond Thunderdome but not Mad Max; The Terminator but not T2).
  • ⚠ recommendations, never similar. The two endpoints sound interchangeable and are not: similar is computed from genre/keyword overlap and is effectively noise — the same probe returned Land of the Blind for Die Hard, The Terminator and RoboCop, and A Man Escaped for Die Hard. recommendations is behavioural and coherent (Terminator → Doomsday, Replicant, Hardware; RoboCop → Repo Men, Upgrade, Chappie). Building on similar would produce baffling channels that read as a Loomarr bug.
  • It explains itself. A candidate carries why: “recommended by 5 of your films.” That is a better approval-card reason than an LLM paraphrase, and it is reproducible — same lineup, same candidates, no tokens.
  • No new dependency and no new safety surface. TMDB is already sanctioned (design.md §14) and the endpoint needs no additional API scope. Candidates enter as catalog.Candidate carrying a Source that records where they came from, then flow through the existing chokepoints unchanged: grounding, scope/audience filters (§4 fail-closed), the re-curation quality bar + title cap (§8.2), and the single accept.Approver gate. Nothing about the approval model moves.
  • ⚠ NOT a /v1/search scope. GET /v1/search?scope=library|tmdb|all (design.md §7.2) is a published enum over corpora a human can type a query against. Adjacency has no query — it is derived from a channel’s lineup — so exposing it there would mean an enum value that ignores q, which is the same shape as the phantom clips scope design.md §7.2 records as a leak corrected rather than implemented. The Source value is internal provenance (Candidate.Source already exists for “which corpus surfaced this, for debugging”), and the retrieval is a catalog method the re-curation path calls directly — not a search enum, and not a new endpoint.
  • Complementary, not a replacement — the corpora MERGE. Every re-curation run consults both: the LLM proposes against intent, the graph proposes against contents, and the union is ranked and cut by the existing quality bar + title cap (§8.2). They cover each other’s weak end — a channel with a thin lineup has a thin graph, which is exactly when the LLM is strongest; a mature channel has a rich graph, which is exactly when the LLM starts repeating itself. Merging rather than alternating keeps a single run’s output complete: a weekly job that consulted only one corpus would make “what did re-curation find?” depend on the parity of the week.
  • Gated by the same AutoCurate opt-in. Adjacency candidates are cheaper than LLM ones (deterministic, no tokens), and it is tempting to run them for every channel on that basis. They are not cheaper in consequence: a net-new adjacency pick is an acquisition, exactly like a net-new LLM pick, and it must clear the same quality bar, the same title cap, and the same accept.Approver gate under the same per-channel opt-in. A channel that has not opted in still gets proposals in the approval queue for an admin to act on (§8.2), from either corpus. Cost is not the axis the gate turns on — spending a user’s disk and bandwidth is.

Where the merge happens — pre-seeding, not post-merging. The suggester’s grounding chokepoint is surfaced: a map of every candidate a tool call returned this run, and buildProposal accepts a pick iff it appears there (§1 — the model cannot smuggle in an id the catalog never returned). That constrains where a second corpus can enter. Merging after generation would mean appending picks the model never saw and the chokepoint never checked — the one thing grounding exists to prevent. So adjacency candidates are pre-seeded into surfaced before generation, and offered to the model in the refine framing alongside the current lineup. Two consequences worth stating:

  • The model still chooses. Pre-seeding widens what it may pick from; it does not place anything. A pre-seeded candidate the model ignores is simply not picked, exactly like a searched one.
  • Grounding is unweakened, because the candidates are real catalog.Candidates with real ids that went through backfillPresence — the same shape a tool call produces. The chokepoint’s invariant (“every pick traces to a candidate the catalog actually returned”) holds verbatim; the set it checks against is just no longer built exclusively by model-initiated tool calls.

This also means adjacency cannot be a pure post-processing step bolted onto re-curation — it has to reach the suggester. A run for a channel with no IntentRef (hand-made, never suggested) therefore gets no adjacency pass either, the same restriction §8.2 already places on re-curation.

The quality bar reads a score the model assigns — which is why an unscored adjacency pick needs a floor. recurate.min_score_pct (§8.2) filters on each acquisition’s confidence, and an omitted one unmarshals to 0, which the filter deliberately treats as “never clears a positive bar” — the conservative direction for spending, and correct for a title the model searched for and then declined to stand behind. An adjacency pick is not that case: it was handed to the model carrying a consensus the model neither computed nor can see. A model that scores only what it found itself would silently zero out the entire second corpus, and the drop count would read as “the bar is working”. So an unscored adjacency pick is credited exactly at the default bar and no higher — enough to be considered on its consensus, never enough to outrank a title the model actually endorsed. A scored one keeps the model’s number in both directions: if the model looked and judged it weak, that judgement stands. This is a floor on an absent score, never a bypass — the title cap, the per-channel opt-in, and the single accept.Approver gate are all unchanged.

⚠ confidence was undefined in the prompt, and the distribution shows it. Across 265 stored proposal items the values were 63% exactly 1.00, 96% ≥ 0.80, and nothing at all between 0 and 0.50 — the model was asserting, not calibrating, because the only mention of the field anywhere in the prompt was the bare "confidence":<0..1> token in the output schema. A bar filtering on an uncalibrated score is close to a no-op. The system prompt now defines the bands (0.9–1.0 squarely-what-was-asked → below 0.4 a stretch), says explicitly not to give everything 0.9+, and tells the model that a pick it was handed still needs its own honest score. This shapes every proposal, not just adjacency ones — it was a pre-existing weakness that building the second corpus happened to expose.

Deliberately deferred: TMDB keywords. The endpoint works and looks tempting for thematic grouping, but the vocabulary is mixed — a probe across the same channel returned real themes (dystopia, alien, creature, atomic bomb) interleaved with mood tags (excited, suspenseful, aggressive), a structural tag (sequel), and a location (los angeles, california). Using it raw would group films by mood and geography and call it a theme. It needs a curated allowlist or a discriminating heuristic first — that is its own design decision, not a detail of this one. Logged in §9 rather than half-built here.

8.4 Proposal and scheduler decision-trace boundary

Proposal explanations are immutable evidence from the suggestion/ranking seam. The trace must carry the exact lexicographic rank tuple and tie-break inputs, plus bounded grounded dispositions, but must not become a second scoring algorithm or include model rationale as deterministic evidence. Approval edits and later channel state do not rewrite its meaning. The tuple’s integer relevance component and closed request/tone/era/include/exclude/refine match booleans are v1’s safe explicit-constraint evidence; raw request terms are not copied into each candidate trace.

Scheduler explanations are a separate seam owned by schedule.ComputeDesiredAt. Each run returns its slots and one ScheduleTrace produced in the same pass. The trace is current-cycle evidence over that run’s approved Lineup, live Availability, resolved ChannelPolicy, and wall-clock; a proposal trace must never be relabeled as current-channel or scheduler evidence.

ScheduleTrace is an ordered, append-only fact stream with four stages:

  1. hard_filter — channel scope/audience, active-rule scope, and seasonal decisions. Never- relaxed audience and explicit scope refusals retain their existing closed reason names.
  2. availability — a movie or series resolves to playable program(s), or its approved entry becomes the configured pod_fill / coming_soon pending outcome. An empty series resolution is unavailable, not an unexplained episode-selection drop.
  3. episode_selection — each safe, in-season episode is kept or omitted by complete, highlights, or holiday. Highlight fallbacks, including unavailable editorial evidence, are explicit full_run_fallback facts. Unsupported holiday episodes instead carry holiday_omitted; a complete matching holiday pool still records positive holiday matches.
  4. placement — the fact records the effective ordering mode, any relaxation, its pre-window deck position, whether the rolling window retained or rotated it out, and its final cycle position. Inserted commercial gaps are placement facts with no content key.

The trace header carries version, effective ordering, the signed 64-bit seed as a lossless decimal string, resolved window duration, and the coarse window index. It is deterministic for the same ComputeDesiredAt inputs. Facts are capped at 1,024 while total counts continue; 256 retained slots are reserved for placement so episode-heavy traces cannot crowd the final stage out. The API reports both totals plus truncated. The two cycle-preview endpoints expose this exact trace beside slots; they do not infer it from the final slot list. UI explanations group the closed facts into concise “why this airs” and “why not” details, while the raw bounded facts remain available to evaluation and support tooling. The trace contains no provider payloads, prompts, rationale, secrets, paths, location, or chain-of-thought.

9. Extensibility — the checklist for “I’m sure I can think of more”

Every future heuristic is added the same way; a heuristic is done when all five exist:

  1. Policy field — schema + default + per-channel override (config doc tier). v1 substrate: built-in Go constants supply the default and policy_json on the channel row holds the per-channel override — a two-tier channel-policy > built-in. The config-design.md registry-default middle tier (the third tier) is deferred until the settings registry lands; it slots into the policy resolver later without touching enforcement. Omitted fields resolve to the built-in constant; an omitted ordering resolves to the channel’s Strategy.
  2. Extractor hint — one line in the suggester’s system prompt + template updates, if the LLM should infer it.
  3. Deterministic enforcer — filter or slotting constraint in the lineup builder; ladder position if relaxable (or listed never-relaxed).
  4. Proposal surface — chip + effect visibility in review.
  5. Tests — binding + violation + relaxation + determinism.

Candidates already visible from here (logged, not v1): dayparting audience ceilings (stricter mornings), episode-quality floors (community ratings), “premiere” slotting for newly-landed backfill, per-holiday custom calendars, inter-channel dedup (don’t air the same movie on two channels the same night), thematic grouping from TMDB keywords (blocked on separating real themes from mood tags and locations — see §8.3), director/cast blocks from TMDB credits (“a John Carpenter night” — the data is clean, the open question is whether it’s a rule What or an ordering mode), and a recency constraint (“nothing re-aired within N days”), which needs an aired-history signal Loomarr does not yet record.

⚠ A candidate source is not a heuristic and does not take the five-point shape above — it has no policy field and no slotting enforcer, because it feeds the proposal pipeline (§8/§8.2), not the lineup builder. Its checklist is different: a catalog.Scope value, a corpus fetch, entry through the existing grounding + audience + approval chokepoints, and provenance the approval card can show. §8.3 is the worked example.

9.1. Discovery certification owns provider-resource uncertainty

The discovery evaluator follows the slice-1 seam from the channel-discovery plan (now in git history; see #1572): one public Runner owns grounded generation, materialized schedule outcomes, judging, and the versioned scorecard. Runner and schedule certification tests inject the eval-only semantic recording Judge, exercise the public Judge.Score(ctx, JudgeEvidence) seam, validate the bounded typed evidence received at that seam, and assert the resulting scorecard behavior and call count. They never reconstruct semantic evidence from a rendered prompt. Production modelJudge renderer and provider request/response tests are a separate, supplemental wire layer: they can prove serialization, routing, parsing, and attribution, but cannot certify schedule semantics or repair, fill in, or rebound evidence that Runner supplied incorrectly. Prompt-substring assertions and private prompt parsers are therefore forbidden as certification evidence. The production suggester’s provider adapter is therefore also the only honest place to enforce a resource ledger around every repair and tool-loop call inside one Suggest.

Per-run limits reset for each case trial, while per-suite limits and uncertainty belong to the whole Runner.Run. With hard token or hosted-USD ceilings, a provider call whose required usage is missing makes the suite ledger permanently uncertain; no later generator, tool-loop turn, or judge may start. Ollama remains explicitly non-billed, rather than being assigned a fictional charge. Failure-stage ownership remains independent of that resource latch: the first retrieval or generation diagnosis in the current trial is retained even if its provider response also makes accounting uncertain, while later trials fail before generation at budget_exhausted. This keeps the scorecard’s closed first-failure vocabulary diagnostic without allowing uncertain paid work to continue.

10. Tests (extends main doc §19 — these join the phase 10/11 gates)

  • Binding: “seasons 1–10” policy → zero slots outside the range across many seeded cycles; era and genre filters likewise.
  • Collections bind, and fail OPEN (§2.2): a scope.collections channel airs only stamped members; an entry whose membership is unresolved still airs (a down media server must not empty a lineup), while a resolved non-member is excluded. The heal is one-time — a fully-stamped channel makes ZERO library calls on the next pass.
  • Fail-closed audience: unrated item + TV-Y7 ceiling → excluded, counted in the exclusion report; TV-MA never appears under any kids ceiling including after full ladder relaxation.
  • Per-episode ceiling (§4): one fixture must reach three different outcomes — an episode rated under the ceiling airs, one rated above it is dropped even though its series cleared the entry gate, and an unrated one airs by inheriting its parent. A test that cannot tell those apart proves nothing, and neither can one asserting on program keys: every episode of a series shares the series key, so assertions run on library item ids. Also pinned: a permissive parent never lifts a rated episode, and a series the ceiling empties yields no slot at all rather than a pending one.
  • Separation with wrap: property test — no episode twice inside the window, no series-gap violation across the cycle seam.
  • Syndication deck: every eligible episode airs exactly once per deck before any repeats.
  • Seasonality under a frozen clock: Oct 15 boosts Halloween items; Jul 14 benches them; exclusive runs offSeason fallback out of window; window roll happens via the sweep.
  • Relaxation: tiny pool → only the breached guards relax, each to the widest value that holds, recorded + surfaced; a breach of one never touches another; never touches audience/scope; pool growth un-relaxes on a later sweep.
  • Determinism: same pool + policy + seed → byte-identical cycle.

11. Build integration

  • Phase 10 (Scheduler): policy enforcement, separation/ordering/seasonal evaluation, relaxation ladder, cycle preview endpoint data.
  • Phase 11 (Suggester): policy extraction in the output contract + grounding of policy values + template policies.
  • Phase 13 (UI): policy chips, exclusion report, cycle preview, relaxation banners.
  • Global defaults + built-in holiday calendar: see the revised config-design.md (per-channel tier + new registry keys).
  • Seed doc: incorporate as docs/programming-design.md in phase 14; the Concepts page inherits §1’s extract/enforce principle.