Lifting the repeat rules for a stretch of the day

[robert-dean]

Status (2026-10-10)

The ask is still one sentence: an operator wants a stretch of the day where the repeat window and
the artist cooldown do not apply. What has changed since this was written is everything around it.

• The surfaces for mode and onEnd are built (2026-09-02), in both SlotEditor and the
  on-air panel, each with copy saying a lift does not reach a dislike.
• The rules bag now has writers, one field at a time. rulesAskedFor in
  director/director.console.service.ts copies flat PutOnAirInput fields (breaks, callins,
  mixInSimilar, chartPositions, requestShow and the three request limits) into
  StationLineupRules. The schedule carries the same switches as nullable columns of their own
  (0075_slot_chart_positions.sql, 0079_slot_breaks.sql, 0081_slot_request_show.sql), and
  ScheduleTickJob.changeOver copies each one into putOnAir. That is the precedent the three
  repeat fields should follow; see "Decisions" for how it changes the one this file made.
• The least-played half (old phases 4 and 5) is superseded. Smart shuffle (director: smart shuffle, fewer repeats across the draw, the desk, the similarity walk and the model #82,
  director/smart.shuffle.ts) leans every draw away from what aired recently through freshWeight
  in rotation.rules.ts, on by default over a 14-day horizon, with FRESH_FLOOR keeping a just-aired
  record at a quarter of its weight rather than at zero. Rediscovery (Rediscovery: bring back liked artists, and play deep cuts #525, director/rediscover.ts)
  then leans toward a liked artist gone quiet and toward deep cuts, and says in so many words that it
  ranks by likes and never by play counts, because ranking by what aired is the feedback loop The station's judgement #37
  warns about. A CandidateTrack.plays count and a least-played weight would now be a third lean
  answering the same question with the signal Rediscovery chose not to use.

What is left is the lift itself: repeatWindowDays, artistCooldownMinutes and maxPerArtist are
declared on StationLineupRules and applied by resolveRules, and nothing sets any of them.
rulesAskedFor does not copy them, PutOnAirInput has no field for them, and schedule_slots has
no column for them. The only way to change how often the station repeats itself is still to change
it for the whole station in rotation.*.

Why the window has to be lifted at all

A Metallica hour is not blocked by anything that names Metallica. It is blocked by three rules that
each look reasonable on their own, and all three have to come off or the hour does not happen:

rule	default	what it does to a one-artist hour
artistCooldownMinutes	40	the second record is refused for forty minutes. This is the one that kills it outright
maxPerArtist	2	a generated batch of fifteen comes back holding two
repeatWindowDays	3	a small pool cannot come round twice, which is what an hour of one artist eventually needs

Three fields, not one switch, and that is the first thing to write down: an "ignore the repeat
window" checkbox alone changes nothing an operator would notice, because the cooldown is what is
actually refusing the records.

What is already in the tree, and what it costs to reach

resolveRules is the whole evaluation path and it needs no change.
rotation.rules.ts resolves tightest-last:
the mode's baseline (station for a rotation, NO_RULES for a setlist or a feature), then
the lineup's own overrides field by field. An overrule is an override, so this is already the code
that applies it. Nothing new judges anything, which keeps docs/internals/director.md § "Who owns
the running order" intact: the schedule stays a document, a resolver and a timer that posts
commands.

The row already holds it. station.lineup.repository.ts selects and writes rules as jsonb, and
StationLineup.rules reads it back. It already carries breaks, callins and the request switches for
every broadcast that asked for them.

The schedule slot carries everything except this. deadair.schedule_slots has grown a column
per switch (breaks, request_show, chart_positions, moods and the rest), and
ScheduleTickJob.changeOver copies each of them into putOnAir. The repeat fields would ride exactly
where brief and breaks ride and for the identical reason the
brief is on the row rather than in a job payload: on_end = 'extend' keeps asking for more, so
anything held only by the batch that started the block is gone within the hour with nothing saying

Decisions

The overrule is the existing per-field bag, on the slot and on putOnAir. Not a new mechanism.
Same shape, same resolver, copied onto the binding at changeover.

Columns, not a jsonb bag on the slot, and this reverses what this file first said. It argued for
one rules jsonb column on schedule_slots mirroring station_lineup.rules, on the grounds that
per-field columns define the shape twice and the next field would need a migration to reach the
schedule. The tree has since added three switches to the slot the other way (0075, 0079, 0081), each
a nullable column with a flat field on PutOnAirInput and one line in rulesAskedFor. A fourth
mechanism for three more fields would leave the slot holding some rules as columns and some in a bag,
which is worse than either. Follow the precedent.

mode: 'feature' is NOT the answer, even though it looks like one. A feature baselines to
NO_RULES, which does turn all three rules off, and also turns off breaks, welcome,
autoExtend and crossfade. An operator who asked for a Metallica hour and got one with a silent
DJ, no greeting for anyone tuning in, and a running order that stops when the batch does has been
answered with something they did not ask for. The overrides are per field precisely so this does not
have to be all-or-nothing, and resolveRules' own comment already makes the argument in the other
direction ("an operator who wants a cooldown inside a long setlist can have one").

A lift never reaches an instruction. rejectDisliked stays, and so does anything
never-play-rules lands: those are absolute by construction and live outside
ResolvedRules for that reason, so this change literally cannot reach them. Say it out loud in the
console copy anyway, because "ignore the repeat rules" reads broader than it is.

Slot-scoped, not artist-scoped. There is no "always bypass the window for Metallica". A rule
about a THING is the ratings mechanism and a rule about a KIND of thing is
never-play-rules; this is a rule about a STRETCH OF THE DAY, which is the
scope the schedule already owns. An artist-scoped exception would be a fourth authority over what may
air, and it would be invisible on the grid.

The manual path gets it too. Three fields on PutOnAirInput, so a spontaneous Metallica hour is possible
without editing the schedule. Without it, the only way to lift a rule is to add a block to the
timetable and wait for the boundary, which is not what an operator pressing "on air" means.

The phases

1. The three fields on PutOnAirInput and through rulesAskedFor. The .ck contract, the
   SDKs it generates, and three more lines in rulesAskedFor. resolveRules already applies them
   and the row already stores them, so this makes a lift expressible with no new evaluation
   anywhere. Commit: a broadcast can be told which repeat rules to lift.
2. The three on schedule_slots, the migration, the repository, the contract and changeOver
   copying them into putOnAir beside breaks. Nothing sets them from the console yet, so the
   schedule behaves exactly as it does today. Commit: a slot carries its own repeat rules.
3. "Rules for this block", a tri-state section (station default / off / a value) for each of the
   three in SlotEditor and on the on-air panel, with the same copy the mode field already carries
   about a lift never reaching a dislike. Commit: an operator can lift the repeat rules for a block.

Each stands alone and 1 is usable from the API and the SDKs before 2 and 3 land.

What the lift does to smart shuffle

Nothing, and that is worth saying before somebody assumes it should. Smart shuffle is a lean and
never a refusal, so it is not one of the three rules a one-artist hour has to lift. With the window
and the cooldown lifted it is what stops a small pool playing the same four records on a loop: a
record that aired twenty minutes ago is drawn at about a quarter of the weight of one that has
rested. If a themed hour ever wants to come round faster than that, FRESH_FLOOR is the knob, and it
is a station-wide one today; making it a fourth per-broadcast field is a separate decision and not
part of this.

What stops a record coming round twice in one batch

What stops an hour repeating a record inside its own batch is not the window, and this is worth
knowing before assuming the lift breaks something: SetGeneratorChain dedupes by songKey across
the batch and against songKeysOf the remaining order. So lifting the window does not produce a
batch holding one record twice. What it produces is a record coming round again a few batches later,
which is the entire point, and what smart shuffle then shapes.

Related

• never-play-rules for the scoping vocabulary (season, daypart, lineup
  mode, schedule slot) and for the bias-versus-veto split this file inherits.
• station-intelligence §5 for the freshness bubble, which is the same
  argument about a stale draw and is deliberately a different mechanism.
• director-and-lineups for the daypart schedule this hangs off, built
  2026-08-19.
• docs/internals/director.md § "Who owns the running order" for why the schedule may never
  evaluate a rule itself.

[robert-dean]

Status check, 2026-09-22 (main at 23b983e)

Only phase 3's narrow form has landed (mode / onEnd from the slot editor and the on-air panel). Phase 1: PutOnAirInput has no rules field. Phase 2: no rules column on schedule_slots. Phases 4 and 5: nothing adds a play count to the candidate draw, and there is no least-played smoke script.

[robert-dean]

Closing: all three phases are built, in #759.

1. PutOnAirInput takes repeatWindowDays, artistCooldownMinutes and maxPerArtist, and rulesAskedFor copies them onto the broadcast's rules. A 0 is the lift and survives as one.
2. schedule_slots has the three as nullable columns (migration 0111), null meaning the mode's own answer, and changeOver carries them onto putOnAir beside breaks.
3. Repeat rules on the slot editor and on Desk → Plan, for a rotation: empty keeps the station's setting and 0 lifts the rule. The copy says a dislike and a never-play rule still apply. A slot saved under another mode keeps whatever the API gave it.

FRESH_FLOOR as a fourth per-broadcast field stays a separate decision, as this discussion said.