@opndev/tennis-match-center 0.0.1

package/lib/auto-planner.mjs

@@ -0,0 +1,1297 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { bandDistance, computeSectionBands } from './court-bands.mjs'
+import { courtUsableAt, runFits } from './court-runs.mjs'
+import {
+  fourTeamUnitLayout, fourTeamUnitSizes, placeLayout,
+} from './four-team-planner.mjs'
+import { groupRuns } from './group-schedule.mjs'
+import { wavesForDivision } from './knockout-waves.mjs'
+import { makeFiveTeamPlanner } from './five-team-planner.mjs'
+import { threeTeamUnitLayout, threeTeamUnits } from './three-team-planner.mjs'
+import { makeOccupancy, courtCanHost } from './occupancy.mjs'
+import { assignKnockout } from './knockout-planner.mjs'
+import { KnockoutDraw } from './knockout-draw.mjs'
+import { Plan } from './plan.mjs'
+import { PlanningDay } from './planning-day.mjs'
+import { activePhase, activeSession } from './sessions.mjs'
+import { MATCH_MINUTES } from './match-time.mjs'
+
+/**
+ * Automatically fills the Planning grid (which competition gets which
+ * court/hour cell) instead of a director dragging out every cell by
+ * hand. Driven entirely by each competition's configured
+ * CompetitionSession rows (its real running order - "Qualifying",
+ * "Main Draw Round 1", ... each starting at its own date+time): a
+ * competition with no sessions configured is never eligible for
+ * auto-fill at all, since there's nothing to say when it should start.
+ *
+ * A session doesn't have a hard end time - it stays "active" (and its
+ * phase keeps claiming capacity) until either the competition's next
+ * session begins or the event runs out of cells. Two sessions on the
+ * same competition are assumed never to overlap in time.
+ *
+ * Group-phase capacity is tracked per date, not as one pooled total
+ * across the whole competition (games_needed_by_date, from
+ * GameCounter::forCompetitionByDate server-side): a 5-team division's
+ * matches are split evenly across its 2 group days by the fixed
+ * template, and a pooled total would happily over-allocate whichever
+ * day comes first, starving the other entirely.
+ *
+ * Knockout capacity is tracked one round ("wave") at a time, not as
+ * one pooled total either (games_needed_by_round, from
+ * GameCounter::knockoutGamesByRoundForCompetition server-side): a
+ * bracket's first round needs the most courts and every later round
+ * needs half as many, tapering down to 1 for the Final. A pooled
+ * total has no way to express that shape - it just claims courts
+ * flatly, hour after hour, until the whole total is used up, giving a
+ * flat block instead of a taper. A competition only starts consuming
+ * its next wave once the current one is fully allocated (mirroring
+ * knockout-schedule.mjs's own round-to-round sequencing), so the
+ * courts freed up as waves shrink go to whichever other competition
+ * still needs them that hour.
+ *
+ * Court preference: pro courts are reserved for pro-designated
+ * competitions (Competition.is_pro - ITF, or "pro" in the competition
+ * or a division's name) and are never given to a non-pro competition;
+ * a pro competition can still use non-pro courts as overflow. Within
+ * one hour, courts are handed out to eligible competitions in the
+ * order they're given (the caller's own priority/sort_order), a
+ * round at a time, so no single competition can claim every court
+ * before another gets a look-in.
+ *
+ * @param {Object} params
+ * @param {Array<{id: number, lit: boolean, pro: boolean, active: boolean}>}
+ *   params.courts
+ * @param {Array<{key: string, lit_required: boolean}>} params.slots
+ *   Hourly columns, in order.
+ * @param {string[]} params.days Y-m-d, in order.
+ * @param {Array<Object>} params.competitions Each carries id, is_pro,
+ *   games_needed {group, knockout}, games_needed_by_date,
+ *   games_needed_by_round and sessions
+ *   [{date, start_time, phase: 'group'|'knockout'}].
+ *   Priority order for court disputes - earlier entries win.
+ * @returns {{blocks: Array<Object>,
+ *   shortfall: Array<{competition_id: number, phase: string,
+ *     missing: number}>,
+ *   warnings: Array<{competition_id: number, kind: string, date: string,
+ *     phase: string}>}}
+ */
+
+const GAMES_PER_POOL_SIZE = { 3: 3, 4: 6, 5: 10 }
+
+export function autoFillPlanning(params) {
+  const {
+    courts,
+    slots: rawSlots,
+    days,
+    competitions: allCompetitions,
+    registrationClosed = false,
+    alwaysByeShortGroups = false,
+    courtOverrides = [],
+    darkFrom = null,
+    dayEnd = '24:00',
+    groupSlotsFromSessions = false,
+    splitRounds = false,
+  } = params
+
+  const competitions = allCompetitions
+    .filter(competition => competition.available_for_planning !== false)
+    .map(competition => ({
+      ...competition,
+      groups: (competition.groups ?? []).map(group => ({
+        ...group,
+        team_ids: group.team_ids
+          ?? Array.from({ length: group.team_count ?? 0 }, (_, i) => i),
+      })),
+    }))
+
+  const slots = withMinutes(rawSlots ?? [])
+  const darkFromMinutes = darkFrom == null ? null : timeToMinutes(darkFrom)
+
+  const dayEndMinutes = timeToMinutes(dayEnd)
+  const plan = new Plan()
+  const blocks = plan.blocks
+  const remainingGroupByDate = new Map()
+  const fiveTeam = makeFiveTeamPlanner()
+  const fourTeamGroups = []
+  const threeTeamGroups = []
+  const boltOnGroups = []
+  const noTemplateWarned = new Set()
+  let fourTeamUnits = null
+  let builtThreeTeamUnits = null
+
+
+  /**
+   * Whether this competition is mostly played on shared pairs.
+   *
+   * A competition of one shape is laid out by that shape's planner and
+   * there is nothing to decide. A mixed one has to choose which goes
+   * first, because the two do not divide into each other: a pair runs
+   * in threes and a 5-team group in fives, so whichever is laid down
+   * second has to fit around the other's leftovers.
+   *
+   * The shape with the most matches takes the courts first. Amateur
+   * Doubles is mostly fives, so its handful of fours fill in around
+   * them. Singles is the other way round, and planning its one 5-team
+   * group first left a court with four slots nothing could use, since
+   * nothing in the tournament is four slots long.
+   */
+  function pooledLeads(competition) {
+    let pooled = 0
+    let owned = 0
+
+    for (const group of competition.groups ?? []) {
+      const teams = (group.team_ids ?? []).length
+      const matches = (teams * (teams - 1)) / 2
+
+      if (shortGroup(group)) {
+        pooled += matches
+      } else {
+        owned += matches
+      }
+    }
+
+    return pooled > owned
+  }
+
+  /**
+   * A group with fewer teams than its division is configured for. It
+   * plays three matches a day on a court pair shared with other short
+   * groups, so it is held back from the ordinary allocation.
+   */
+  /**
+   * Whether a group is played on a shared pair of courts rather than
+   * one of its own.
+   *
+   * Every 4-team group is: three rounds of two matches, a round taking
+   * both courts, two or three groups taking turns. That is how a
+   * 4-team group is played, not a special case for an uneven one.
+   *
+   * The exception is a group of four sitting in a division configured
+   * for five. While registration is open it may still fill from the
+   * waitlist, so capacity is held for it as a five - the spare cells
+   * are the point, not waste. Once registration closes it is a 4-team
+   * group like any other.
+   */
+  function shortGroup(group) {
+    const teams = (group.team_ids ?? []).length
+
+    if (teams === 3) {
+      return group.pool_size >= 4
+    }
+
+    if (teams !== 4) {
+      return false
+    }
+
+    return group.pool_size === 4
+      || (registrationClosed && !alwaysByeShortGroups)
+  }
+
+  /*
+   * The dates a competition is actually in its group phase.
+   *
+   * group_dates says which days the draw wants; the sessions say what
+   * the competition is doing on them, and the two disagree whenever
+   * the last group date is also the day it switches to knockout.
+   *
+   * A unit cuts its sequence into one part per date. Counting a
+   * knockout day among them handed a half to a day that then refused
+   * it, and the matches were simply lost: three of the four pooled
+   * competitions placed exactly half of theirs.
+   */
+  function groupDatesFor(competition) {
+    const sessions = sortedSessions.get(competition.id) ?? []
+
+    return (competition.group_dates ?? []).filter(date => {
+      const own = slotsForDate(sessions, date, darkFromMinutes, dayEndMinutes)
+
+      return own.length > 0 && own[0].phase === 'group'
+    })
+  }
+
+  function buildFourTeamUnits() {
+    const pools = new Map()
+
+    for (const entry of fourTeamGroups) {
+      const dates = groupDatesFor(entry.competition)
+      const pairing = entry.group.pairing ?? 'auto'
+
+      const key = [
+        entry.group.is_pro === true ? 'pro' : 'open', pairing, ...dates,
+      ].join('|')
+
+      if (!pools.has(key)) {
+        pools.set(key, {
+          dates, isPro: entry.group.is_pro === true, pairing, entries: [],
+        })
+      }
+
+      pools.get(key).entries.push(entry)
+    }
+
+    const units = []
+
+    for (const { dates, isPro, pairing, entries } of pools.values()) {
+      const dense = pairing === 'triples'
+        ? true
+        : pairing === 'pairs' ? false : undefined
+      const short = entries
+        .filter(entry => (entry.group.team_ids ?? []).length < 4)
+      const full = entries
+        .filter(entry => (entry.group.team_ids ?? []).length >= 4)
+
+      const pooled = short.length >= 2
+        ? [{ list: full, tail: false }, { list: short, tail: true }]
+        : [{ list: entries, tail: false }]
+
+      for (const { list } of pooled) {
+        let cursor = 0
+
+        for (const size of fourTeamUnitSizes(list.length, { dense })) {
+          units.push({
+            dates,
+            isPro,
+            divisionId: list[cursor]?.group.division_id ?? null,
+            entries: list.slice(cursor, cursor + size),
+            placed: new Set(),
+          })
+          cursor += size
+        }
+      }
+    }
+
+    return units
+  }
+
+  /**
+   * The same bundling as buildFourTeamUnits, for genuine 3-team
+   * groups. No "short"/dense split here - a group reaching this pass
+   * (see the group loop above) is already exactly 3 real teams, never
+   * a vacant-seat bye, and there is no pairs/triples choice to honour
+   * (see paired-court-planner.mjs's TODO).
+   */
+  function buildThreeTeamUnits() {
+    const pools = new Map()
+
+    for (const entry of threeTeamGroups) {
+      const dates = groupDatesFor(entry.competition)
+
+      const isTeamCup = (entry.group.team_size ?? 2) >= 4
+
+      const key = isTeamCup
+        ? `solo:${entry.group.id}`
+        : [entry.group.is_pro === true ? 'pro' : 'open', ...dates].join('|')
+
+      if (!pools.has(key)) {
+        pools.set(key, {
+          dates, isPro: entry.group.is_pro === true, entries: [],
+        })
+      }
+
+      pools.get(key).entries.push(entry)
+    }
+
+    const units = []
+
+    for (const { dates, isPro, entries } of pools.values()) {
+      const built = entries.length === 1 ? [entries] : threeTeamUnits(entries)
+
+      for (const unitEntries of built) {
+        units.push({
+          dates,
+          isPro,
+          divisionId: unitEntries[0]?.group.division_id ?? null,
+          entries: unitEntries,
+          placed: new Set(),
+        })
+      }
+    }
+
+    return units
+  }
+
+  const knockoutUnits = []
+
+  const proDivisions = new Set()
+
+  for (const competition of competitions) {
+    for (const group of competition.groups ?? []) {
+      if (group.is_pro === true && group.division_id != null) {
+        proDivisions.add(group.division_id)
+      }
+    }
+  }
+
+  const sortedSessions = new Map()
+  for (const competition of competitions) {
+    sortedSessions.set(
+      competition.id,
+      [...competition.sessions].sort((a, b) =>
+        (a.date + a.start_time).localeCompare(b.date + b.start_time)
+      )
+    )
+  }
+
+  for (const competition of competitions) {
+    const derived = (competition.divisions ?? [])
+      .filter(division =>
+        division.knockout_matches != null || division.team_count != null
+      )
+      .map(division => ({
+        division_id: division.id,
+        division_name: division.name,
+        division_gender: division.gender ?? null,
+        level: division.level ?? 0,
+        waves: wavesForDivision(division, { itf: competition.itf === true }),
+      }))
+      .filter(bracket => bracket.waves.length > 0)
+
+    const brackets = derived.length > 0
+      ? derived
+      : (competition.knockout_rounds_by_division
+        ?? (competition.games_needed_by_round?.length
+          ? [competition.games_needed_by_round]
+          : []))
+
+    for (const bracket of brackets) {
+      const waves = Array.isArray(bracket) ? bracket : bracket.waves
+      const division = Array.isArray(bracket) ? null : bracket
+
+      knockoutUnits.push(new KnockoutDraw({
+        competition,
+        waves,
+        divisionId: division?.division_id ?? null,
+        divisionName: division?.division_name ?? null,
+        divisionGender: division?.division_gender ?? null,
+        level: division?.level ?? 0,
+        isPro: proDivisions.has(division?.division_id),
+      }))
+    }
+
+    if (Array.isArray(competition.groups) && competition.groups.length === 0) {
+      continue
+    }
+
+    const boltOn = pooledLeads(competition)
+
+    for (const group of competition.groups ?? []) {
+      if (shortGroup(group)) {
+        const size = group.pool_size ?? group.team_ids.length
+        const asFull = alwaysByeShortGroups || !registrationClosed
+        const padded = asFull && size > group.team_ids.length
+          ? paddedWithByes(group, size)
+          : group
+
+        fourTeamGroups.push({ competition, group: padded })
+        continue
+      }
+
+      if ((group.team_ids ?? []).length === 3) {
+        threeTeamGroups.push({ competition, group, placed: new Set() })
+        continue
+      }
+
+      if (boltOn) {
+        boltOnGroups.push({ competition, group, placed: new Set() })
+        continue
+      }
+
+      for (const { date, count } of fiveTeam.enqueue({
+        competition,
+        group,
+        dates: groupDatesFor(competition),
+        asFull: alwaysByeShortGroups || !registrationClosed,
+      })) {
+        const key = groupKey(competition.id, date)
+        remainingGroupByDate.set(
+          key, (remainingGroupByDate.get(key) ?? 0) + count
+        )
+      }
+    }
+  }
+
+  function remainingFor(competitionId, phase, date) {
+    return remainingGroupByDate.get(groupKey(competitionId, date)) ?? 0
+  }
+
+  function decrement(competitionId, phase, date) {
+    const groupDateKey = groupKey(competitionId, date)
+    remainingGroupByDate.set(
+      groupDateKey, remainingGroupByDate.get(groupDateKey) - 1
+    )
+  }
+
+  const activeCourts = courts.filter(court => court.active)
+  const proCourts = activeCourts.filter(court => court.pro)
+  const openCourts = activeCourts.filter(court => !court.pro)
+
+  const overridesByDate = new Map()
+
+  for (const override of courtOverrides) {
+    if (!overridesByDate.has(override.date)) {
+      overridesByDate.set(override.date, new Map())
+    }
+
+    overridesByDate.get(override.date).set(
+      override.court_id,
+      override.available_from ? timeToMinutes(override.available_from) : null
+    )
+  }
+
+  /**
+   * The non-pro courts usable on this date - openCourts, plus any
+   * normally-pro court a director has opened up for the day. The
+   * override travels with the court object itself (availableFromMinutes),
+   * so courtUsableAt can enforce it without needing to know the date.
+   */
+  function openCourtsFor(date) {
+    const overrides = overridesByDate.get(date)
+
+    if (!overrides) {
+      return openCourts
+    }
+
+    const opened = new Map(proCourts
+      .filter(court => overrides.has(court.id))
+      .map(court => [court.id, {
+        ...court, availableFromMinutes: overrides.get(court.id),
+      }]))
+
+    if (opened.size === 0) {
+      return openCourts
+    }
+
+    return activeCourts
+      .filter(court => !court.pro || opened.has(court.id))
+      .map(court => opened.get(court.id) ?? court)
+  }
+
+  /**
+   * The hour the day's first competition opens, which every
+   * competition's slots are measured from.
+   */
+  function anchorFor(date) {
+    const opens = []
+
+    for (const competition of competitions) {
+      const session = activeSession(
+        sortedSessions.get(competition.id) ?? [], date
+      )
+
+      if (!session) {
+        continue
+      }
+
+      if (session.phase === 'knockout') {
+        const stillPlaying = knockoutUnits.some(draw =>
+          draw.competition.id === competition.id && !draw.done
+        )
+
+        if (!stillPlaying) {
+          continue
+        }
+      }
+
+      opens.push(timeToMinutes(session.start_time))
+    }
+
+    return opens.length === 0 ? null : Math.min(...opens)
+  }
+
+  function slotsFor(competitionId, date) {
+    if (!groupSlotsFromSessions && slots.length > 0) {
+      return slots
+    }
+
+    return slotsForDate(
+      sortedSessions.get(Number(competitionId)) ?? [],
+      date, darkFromMinutes, dayEndMinutes, anchorFor(date)
+    )
+  }
+
+  fiveTeam.prepare({ slotsFor, courts: openCourts, usable: courtUsableAt })
+
+  for (const date of days) {
+    const taken = makeOccupancy()
+
+    const slotsByCompetition = new Map(
+      competitions.map(competition => [
+        competition.id,
+        competition.slots
+          ? withMinutes(competition.slots)
+          : ((groupSlotsFromSessions || slots.length === 0)
+            ? slotsForDate(
+              sortedSessions.get(competition.id) ?? [],
+              date, darkFromMinutes, dayEndMinutes, anchorFor(date)
+            )
+            : slots),
+      ])
+    )
+
+    function assign(entries, requireLit) {
+      const eligible = entries.filter(({ competition, phase }) =>
+        remainingFor(competition.id, phase, date) > 0
+      )
+
+      if (eligible.length === 0) {
+        return
+      }
+
+      const context = {
+        date, taken, blocks, remainingFor, decrement, fiveTeam, requireLit,
+      }
+
+      assignCourts(
+        proCourts,
+        eligible.filter(({ competition }) => competition.is_pro),
+        { ...context, proCourt: true }
+      )
+
+      assignCourts(openCourtsFor(date), eligible, context)
+    }
+
+    const timeline = []
+
+    for (const competition of competitions) {
+      const own = slotsByCompetition.get(competition.id) ?? []
+
+      const runLength = fiveTeam.runLengthFor(competition.id, date)
+
+      own.forEach((slot, slotIndex) => {
+        const phase = slot.phase
+          ?? activePhase(sortedSessions.get(competition.id), date, slot.key)
+
+        if (phase !== 'group') {
+          return
+        }
+
+        const last = own[Math.min(slotIndex + runLength - 1, own.length - 1)]
+        const needsLight = runNeedsLight(
+          own, slotIndex, runLength, darkFromMinutes
+        )
+
+        timeline.push({
+          competition, phase: 'group', slots: own, slotIndex, slot, needsLight,
+        })
+      })
+    }
+
+    const lit = byStartTime(timeline.filter(e => e.needsLight), true)
+
+    for (const [, entries] of lit) {
+      assign(entries, true)
+    }
+
+    const daylight = byStartTime(timeline.filter(e => !e.needsLight), false)
+
+    for (const [, entries] of daylight) {
+      assign(entries, false)
+    }
+
+    function placeGroupUnit(unit, unitLayoutFn) {
+      const unitDates = unit.dates.slice(0, 2)
+      const dayIndex = unitDates.indexOf(date)
+
+      if (dayIndex === -1 || unit.placed.has(date)) {
+        return false
+      }
+
+      const unitSlots = slotsByCompetition
+        .get(unit.entries[0].competition.id) ?? slots
+
+      if (unitSlots.length === 0 || unitSlots[0].phase === 'knockout') {
+        return false
+      }
+
+      const sequence = unitLayoutFn(unit.entries.map(entry => ({
+        id: entry.group.id,
+        teamIds: entry.group.team_ids,
+        groupSize: entry.group.pool_size,
+      })))
+
+      const firstDay = Math.floor(sequence.length / unitDates.length)
+      const layout = dayIndex === 0
+        ? sequence.slice(0, firstDay)
+        : sequence.slice(firstDay)
+
+      const before = blocks.length
+
+      const placed = placeLayout({
+        layout,
+        lookup: groupId => {
+          const entry = unit.entries.find(x => x.group.id === groupId)
+
+          return {
+            id: entry.group.id,
+            competitionId: entry.competition.id,
+            divisionId: entry.group.division_id ?? null,
+            divisionName: entry.group.division_name ?? null,
+            divisionGender: entry.group.division_gender ?? null,
+            groupName: entry.group.name ?? null,
+          }
+        },
+        courts: unit.isPro ? proCourts : openCourtsFor(date),
+        slots: unitSlots,
+        date,
+        occupancy: taken,
+        darkFrom: darkFromMinutes,
+        blocks,
+      })
+
+      if (placed) {
+        unit.placed.add(date)
+        return new Set(blocks.slice(before).map(block => block.court_id)).size
+      }
+
+      return false
+    }
+
+    function placeGroupUnitsForDate(units, unitLayoutFn) {
+      for (const kind of [true, false]) {
+        const due = units.filter(unit =>
+          unit.isPro === kind && !unit.placed.has(date)
+            && unit.dates.includes(date)
+        )
+
+        if (due.length === 0) {
+          continue
+        }
+
+        const order = []
+
+        for (const unit of due) {
+          if (!order.includes(unit.divisionId)) {
+            order.push(unit.divisionId)
+          }
+        }
+
+        const roomCourts = (kind ? proCourts : openCourtsFor(date)).length
+
+        const quota = new Map(order.map((divisionId, index) => {
+          const mine = due.filter(unit => unit.divisionId === divisionId)
+          const share = mine.length / due.length
+
+          return [
+            divisionId,
+            index === order.length - 1
+              ? Infinity
+              : Math.max(2, Math.round(share * roomCourts)),
+          ]
+        }))
+
+        const claimed = new Map()
+
+        for (const unit of due) {
+          const mine = claimed.get(unit.divisionId) ?? 0
+
+          if (mine >= (quota.get(unit.divisionId) ?? Infinity)) {
+            continue
+          }
+
+          const courtsUsed = placeGroupUnit(unit, unitLayoutFn)
+
+          if (courtsUsed) {
+            claimed.set(
+              unit.divisionId, (claimed.get(unit.divisionId) ?? 0) + courtsUsed
+            )
+          }
+        }
+
+        for (const unit of due) {
+          if (!unit.placed.has(date)) {
+            placeGroupUnit(unit, unitLayoutFn)
+          }
+        }
+      }
+    }
+
+    fourTeamUnits ??= buildFourTeamUnits()
+    placeGroupUnitsForDate(fourTeamUnits, fourTeamUnitLayout)
+
+    builtThreeTeamUnits ??= buildThreeTeamUnits()
+    placeGroupUnitsForDate(builtThreeTeamUnits, threeTeamUnitLayout)
+
+    for (const entry of boltOnGroups) {
+      const opened = groupDatesFor(entry.competition).includes(date)
+
+      if (entry.placed.has(date) || !opened) {
+        continue
+      }
+
+      const own = slotsByCompetition.get(entry.competition.id) ?? []
+
+      if (own.length === 0 || own[0].phase === 'knockout') {
+        continue
+      }
+
+      const dates = groupDatesFor(entry.competition)
+      const teamIds = entry.group.team_ids ?? []
+      const size = entry.group.pool_size ?? teamIds.length
+
+      const asFull = alwaysByeShortGroups || !registrationClosed
+      const seats = asFull && size > teamIds.length
+        ? Array.from({ length: size }, (_, i) => teamIds[i] ?? -(i + 1))
+        : teamIds
+
+      const runs = groupRuns({ teamIds: seats, groupSize: size })
+
+      if (runs.length === 0 && teamIds.length > 0
+        && !noTemplateWarned.has(entry.group.id)) {
+        noTemplateWarned.add(entry.group.id)
+
+        plan.warn({
+          competition_id: entry.competition.id,
+          kind: 'no-template',
+          division_id: entry.group.division_id ?? null,
+          division_name: entry.group.division_name ?? null,
+          group_id: entry.group.id,
+          group_name: entry.group.name ?? null,
+          teams: teamIds.length,
+        })
+
+        plan.short(
+          entry.competition, 'group',
+          GAMES_PER_POOL_SIZE[entry.group.pool_size] ?? 6
+        )
+      }
+
+      const today = runs.filter(run =>
+        (dates.length === 1 ? dates[0] : dates[run.day - 1]) === date
+      )
+      const cells = today.flatMap(run => run.positions)
+
+      if (cells.length === 0) {
+        continue
+      }
+
+      const laneCourts = entry.group.is_pro === true
+        ? proCourts
+        : openCourtsFor(date)
+      let landed = false
+
+      const last = own.length - cells.length
+
+      for (let start = 0; start <= last && !landed; start++) {
+        const window = own.slice(start, start + cells.length)
+
+        for (const court of laneCourts) {
+          const usable = window.every(slot =>
+            courtUsableAt(court, slot)
+              && taken.free(
+                date, court.id, slot.start_minutes, slot.end_minutes
+              )
+          )
+
+          if (!usable) {
+            continue
+          }
+
+          window.forEach((slot, offset) => {
+            blocks.push({
+              competition_id: entry.competition.id,
+              division_id: entry.group.division_id ?? null,
+              division_name: entry.group.division_name ?? null,
+              division_gender: entry.group.division_gender ?? null,
+              group_id: entry.group.id,
+              group_name: entry.group.name ?? null,
+              phase: 'group',
+              round: 'group',
+              match_slot: cells[offset] ?? null,
+              court_id: court.id,
+              date,
+              slot: slot.key,
+            })
+
+            taken.take(date, court.id, slot.start_minutes, slot.end_minutes)
+          })
+
+          entry.placed.add(date)
+          landed = true
+          break
+        }
+      }
+
+      if (!landed) {
+        plan.short(entry.competition, 'group', cells.length)
+      }
+    }
+
+    const day = new PlanningDay({
+      date,
+      proCourts,
+      openCourts: openCourtsFor(date),
+      slotsByCompetition,
+      occupancy: taken,
+      plan,
+      darkFromMinutes,
+    })
+
+    assignKnockout(day, {
+      competitions,
+      draws: knockoutUnits,
+      sessions: sortedSessions,
+      split: splitRounds,
+    })
+  }
+
+  refuseLateStarts({
+    competitions, sortedSessions, plan, overridesByDate,
+    slotsFor, runLengthFor: (id, date) => fiveTeam.runLengthFor(id, date),
+  })
+
+  const placed = plan.blocks.filter(block => !plan.dropped.has(block))
+
+  for (const entry of threeTeamGroups) {
+    const got = placed.filter(block =>
+      block.group_id === entry.group.id && block.phase === 'group'
+    ).length
+    const missing = GAMES_PER_POOL_SIZE[3] - got
+
+    if (missing > 0) {
+      plan.short(entry.competition, 'group', missing)
+    }
+  }
+
+  for (const competition of competitions) {
+    if (competition.sessions.length === 0) {
+      continue
+    }
+
+    const missingGroup = [...remainingGroupByDate]
+      .filter(([key]) =>
+        key.slice(0, key.indexOf(':')) === String(competition.id)
+      )
+      .reduce((total, [, left]) => total + Math.max(left, 0), 0)
+
+    const missingKnockout = knockoutUnits
+      .filter(draw => draw.competition.id === competition.id)
+      .reduce((total, draw) => total + draw.unplanned, 0)
+
+    plan.short(competition, 'group', missingGroup)
+    plan.short(competition, 'knockout', missingKnockout)
+  }
+
+  const result = plan.result(competitions)
+
+  const overflow = knockoutOverflow(competitions, result)
+
+  if (splitRounds || overflow === 0) {
+    return result
+  }
+
+  const retried = autoFillPlanning({ ...params, splitRounds: true })
+
+  return knockoutOverflow(competitions, retried) < overflow ? retried : result
+}
+
+/**
+ * How much of the event's knockout did not fit where it was meant to:
+ * capacity nobody could place at all, plus every cell that landed on
+ * a day its competition's knockout was never scheduled for.
+ *
+ * A competition with no knockout session of its own is not counted -
+ * it was never given a day to overflow from.
+ */
+/**
+ * When a session opens, allowing for the rhythm runs are laid out on.
+ *
+ * Runs start on a section boundary, so a session opening part way
+ * through one is due on at the next: that is the rhythm, not lateness.
+ *
+ * @param {Array} own The session's own slots, in order.
+ * @param {string} startTime The session's configured start.
+ * @param {number} runLength Slots to a run in this phase.
+ * @returns {?Object} The slot it is due on, or null where the day has
+ *   no such slot at all.
+ */
+/**
+ * Whether a group run has to have a lit court.
+ *
+ * A question about the whole run, not the slot it starts in: everyone
+ * on court at the same time plays in the same conditions, so a section
+ * running past dark needs light from its first match. Where no
+ * darkness time is given, the slots' own flags are all there is to go
+ * on.
+ *
+ * @param {Array} own The competition's slots for the day.
+ * @param {number} slotIndex Where the run starts.
+ * @param {number} runLength Slots to the run.
+ * @param {?number} darkFromMinutes When the light goes, if known.
+ * @returns {boolean}
+ */
+function runNeedsLight(own, slotIndex, runLength, darkFromMinutes) {
+  if (darkFromMinutes == null) {
+    return own.slice(slotIndex, slotIndex + runLength)
+      .some(slot => slot.lit_required)
+  }
+
+  const last = own[Math.min(slotIndex + runLength - 1, own.length - 1)]
+
+  return last.end_minutes > darkFromMinutes
+}
+
+/**
+ * Timeline entries grouped by the moment they start.
+ *
+ * Runs needing light are worked latest first, because only a lit court
+ * can serve them and the evening runs out: the scarce capacity is
+ * spent before the day's abundant daytime capacity is. Everything else
+ * goes earliest first.
+ *
+ * @param {Array} entries
+ * @param {boolean} requireLit
+ * @returns {Array<[number, Array]>} Start minute and its entries.
+ */
+function byStartTime(entries, requireLit) {
+  const byStart = new Map()
+
+  for (const entry of entries) {
+    const key = entry.slot.start_minutes
+
+    if (!byStart.has(key)) {
+      byStart.set(key, [])
+    }
+
+    byStart.get(key).push(entry)
+  }
+
+  return [...byStart.entries()]
+    .sort((a, b) => (requireLit ? b[0] - a[0] : a[0] - b[0]))
+}
+
+/**
+ * A short group filled out to its full size with byes.
+ *
+ * The empty seats travel as negative ids: a template needs a team in
+ * every position to lay out at all, and a negative id can never
+ * collide with a real one.
+ *
+ * @param {Object} group
+ * @param {number} size The group's full pool size.
+ * @returns {Object} A copy, padded.
+ */
+function paddedWithByes(group, size) {
+  return {
+    ...group,
+    team_ids: Array.from(
+      { length: size }, (_, i) => group.team_ids[i] ?? -(i + 1)
+    ),
+  }
+}
+
+function dueSlot(own, startTime, runLength) {
+  const from = own.findIndex(slot => slot.key >= startTime)
+
+  if (from === -1) {
+    return null
+  }
+
+  return own[Math.ceil(from / runLength) * runLength] ?? null
+}
+
+/**
+ * Drops the plan for any competition that could not open when it was
+ * told to, and says so.
+ *
+ * A competition starts when its session says. If not one of its
+ * divisions can take a court in that hour, the configuration and the
+ * courts disagree, and that is a planning error rather than something
+ * to work around quietly - sliding it later and saying nothing is how
+ * a start time nobody chose survived a week of planning. The cells it
+ * would have taken are left for whoever can use them.
+ *
+ * A court override on the date is a director's own deliberate,
+ * informed reason to start later, so it is exempt.
+ *
+ * @param {Object} params
+ * @param {Plan} params.plan Refusals and warnings are recorded on it.
+ */
+function refuseLateStarts({
+  competitions, sortedSessions, plan, overridesByDate,
+  slotsFor, runLengthFor,
+}) {
+  for (const competition of competitions) {
+    for (const session of sortedSessions.get(competition.id) ?? []) {
+      const mine = plan.cellsFor(competition, session.date, session.phase)
+
+      if (mine.length === 0 || overridesByDate.has(session.date)) {
+        continue
+      }
+
+      const own = slotsFor(competition.id, session.date)
+        .filter(slot => (slot.phase ?? session.phase) === session.phase)
+
+      const runLength = session.phase === 'group'
+        ? runLengthFor(competition.id, session.date)
+        : 1
+
+      const due = dueSlot(own, session.start_time, runLength)
+
+      if (!due) {
+        continue
+      }
+
+      const opens = due.start_minutes ?? timeToMinutes(due.key)
+      const earliest = Math.min(...mine.map(block => timeToMinutes(block.slot)))
+
+      if (earliest <= opens) {
+        continue
+      }
+
+      plan.refuse(competition, session.phase, mine)
+
+      plan.warn({
+        competition_id: competition.id,
+        kind: 'late-start',
+        date: session.date,
+        phase: session.phase,
+        expected: minutesToTime(opens),
+        earliest: minutesToTime(earliest),
+        late: earliest - opens,
+        refused: true,
+      })
+    }
+  }
+}
+
+function knockoutOverflow(competitions, { blocks, shortfall }) {
+  const scheduled = new Map(
+    competitions.map(competition => [
+      competition.id,
+      new Set(
+        (competition.sessions ?? [])
+          .filter(session => session.phase === 'knockout')
+          .map(session => session.date)
+      ),
+    ])
+  )
+
+  const spilled = blocks.filter(block => {
+    if (block.phase !== 'knockout') {
+      return false
+    }
+
+    const days = scheduled.get(block.competition_id)
+
+    return days != null && days.size > 0 && !days.has(block.date)
+  }).length
+
+  const missing = shortfall
+    .filter(entry => entry.phase === 'knockout')
+    .reduce((total, entry) => total + entry.missing, 0)
+
+  return spilled + missing
+}
+
+function groupKey(competitionId, date) {
+  return `${competitionId}:${date}`
+}
+
+
+/**
+ * Hands out one court per eligible entry per pass, looping until
+ * either the court list or every entry's remaining need is exhausted -
+ * so a lone eligible competition gets every court offered, and several
+ * eligible competitions split them round by round in priority order.
+ *
+ * A group-phase entry claims a whole run of consecutive slots on one
+ * court at once (group_run_length - a 5-team group's 5 matches), and
+ * only on a court that can host every slot of that run. A court that
+ * runs out of light partway through cannot host the group at all, so
+ * it is never given the run's opening slot either.
+ */
+/**
+ * Which queued run belongs on a court that has already been taken.
+ *
+ * The court chose itself by being the lowest free one that fits the
+ * whole run; this asks the planner which run should have it, scored on
+ * which division is owed a run and whose band this court falls in -
+ * hence the court's position along the row rather than its id. The row
+ * is the courts playable in this slot, so at night the position is
+ * measured against the lit ones alone.
+ *
+ * @param {Object} params
+ * @param {string} params.phase Only a group phase has a queue at all.
+ * @param {Array} params.usable Courts playable in this slot, in order.
+ * @param {boolean} params.proCourt Whether the court taken is a pro
+ *   one. A pro court takes a pro division's run and nothing else, and
+ *   a pro run waits for one rather than taking an open court, so a
+ *   mismatch comes back blocked and the court is left empty.
+ * @returns {?Object} The chosen run, {blocked: true}, or null where
+ *   the phase has no queue or the queue is empty.
+ */
+function pickRun({
+  planner, phase, competition, date, sectionIndex, court, usable, proCourt,
+}) {
+  if (phase !== 'group') {
+    return null
+  }
+
+  return planner.pick(competition.id, date, sectionIndex, {
+    courtPosition: usable.indexOf(court),
+    courtCount: usable.length,
+  }, { proCourt })
+}
+
+function assignCourts(courtList, eligible, context) {
+  const { date, taken, blocks, remainingFor, decrement, fiveTeam } = context
+
+  let progressed = true
+
+  while (progressed) {
+    progressed = false
+
+    for (const entry of eligible) {
+      const { competition, phase, slots, slotIndex } = entry
+      const slot = slots[slotIndex]
+
+      const available = courtList.filter(court =>
+        courtUsableAt(court, slot) && taken.free(
+          date, court.id, slot.start_minutes, slot.end_minutes
+        )
+      )
+
+      if (available.length === 0) {
+        continue
+      }
+
+      const remaining = remainingFor(competition.id, phase, date)
+
+      if (remaining <= 0) {
+        continue
+      }
+
+      const planner = fiveTeam
+      const runLength = phase === 'group'
+        ? planner.runLengthFor(competition.id, date)
+        : 1
+
+      if (slotIndex % runLength !== 0) {
+        continue
+      }
+
+      const sectionIndex = Math.floor(slotIndex / runLength)
+
+      function fits(court) {
+        return runFits(court, { ...context, slots, slotIndex }, runLength)
+      }
+
+      const courtPosition = available.findIndex(fits)
+
+      if (courtPosition === -1) {
+        continue
+      }
+
+      const [court] = available.splice(courtPosition, 1)
+
+      const picked = pickRun({
+        planner, phase, competition, date, sectionIndex, court,
+        usable: courtList.filter(court => courtUsableAt(court, slot)),
+        proCourt: context.proCourt === true,
+      })
+
+      if (picked?.blocked || (phase === 'group' && !picked)) {
+        continue
+      }
+
+      const run = picked
+        ? planner.commit(competition.id, date, sectionIndex, picked.index)
+        : null
+
+      for (let i = 0; i < Math.min(runLength, remaining); i++) {
+        const runSlot = slots[slotIndex + i]
+
+        const matchSlot = run ? (run.positions[i] ?? null) : null
+
+        blocks.push({
+          competition_id: competition.id,
+          division_id: run?.divisionId ?? null,
+          division_name: run?.divisionName ?? null,
+          division_gender: run?.divisionGender ?? null,
+          group_id: run?.groupId ?? null,
+          group_name: run?.groupName ?? null,
+          phase,
+          round: phase === 'group' ? 'group' : null,
+          match_slot: matchSlot,
+          court_id: court.id,
+          date,
+          slot: runSlot.key,
+        })
+
+        taken.take(date, court.id, runSlot.start_minutes, runSlot.end_minutes)
+        decrement(competition.id, phase, date)
+      }
+
+      progressed = true
+    }
+  }
+}
+
+/**
+ * When a slot starts and ends, in minutes past midnight.
+ *
+ * The server sends these, but a slot may arrive as nothing more than a
+ * key ("09:00"), so they are derived where missing: a slot runs until
+ * the next one starts, and the last runs a match's length.
+ */
+function withMinutes(slots) {
+  return slots.map((slot, index) => {
+    const start = slot.start_minutes ?? timeToMinutes(slot.key)
+    const next = slots[index + 1]
+    const end = slot.end_minutes
+      ?? (next
+        ? (next.start_minutes ?? timeToMinutes(next.key))
+        : start + MATCH_MINUTES)
+
+    return { ...slot, start_minutes: start, end_minutes: end }
+  })
+}
+
+
+export function slotsForDate(
+  sessions, date, darkFromMinutes, dayEnd = 24 * 60, anchor = null
+) {
+  const active = activeSession(sessions, date)
+
+  if (!active) {
+    return []
+  }
+
+  const length = Math.max(1, active.playtime ?? MATCH_MINUTES)
+  const opens = timeToMinutes(active.start_time)
+
+  const from = anchor == null || anchor > opens
+    ? opens
+    : anchor + Math.ceil((opens - anchor) / length) * length
+
+  const slots = []
+
+  for (let start = from; start + length <= dayEnd; start += length) {
+    slots.push({
+      key: minutesToTime(start),
+      start_minutes: start,
+      end_minutes: start + length,
+      lit_required: darkFromMinutes != null && start + length > darkFromMinutes,
+      phase: active.phase,
+    })
+  }
+
+  return slots
+}
+
+function minutesToTime(minutes) {
+  const hours = Math.floor(minutes / 60)
+  return `${String(hours).padStart(2, '0')}`
+    + `:${String(minutes % 60).padStart(2, '0')}`
+}
+
+function timeToMinutes(key) {
+  const [hours, minutes] = String(key).split(':').map(Number)
+  return hours * 60 + (minutes || 0)
+}
+
+export { activeSession }