@opndev/tennis-match-center 0.0.1

package/lib/run-queue-planner.mjs

@@ -0,0 +1,603 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { bandDistance, computeSectionBands, sectionsFor } from './court-bands.mjs'
+import { groupRuns } from './group-schedule.mjs'
+
+/**
+ * Where a group should land the day after playing a given section:
+ * S1 to S3, S2 to S4, S3 to S1, S4 to S2 - prio.pl's rotation. A
+ * group that played late one day plays early the next and the other
+ * way round, so nobody gets two late finishes or two early starts.
+ */
+const SECTION_OFFSET = { 0: 2, 1: 3, 2: 0, 3: 1 }
+
+// Mirrors GameCounter::GAMES_PER_GROUP server-side: how many matches a
+// full group of this size plays. Used only to report a group with no
+// known match template (see enqueue()'s own guard below) against the
+// same "assume everyone showed up" baseline games_needed itself uses.
+const GAMES_PER_POOL_SIZE = { 3: 3, 4: 6, 5: 10 }
+
+const queueKey = (competitionId, date) => `${competitionId}:${date}`
+
+/**
+ * Group play for any shape whose groups run their whole round robin as
+ * one unbroken stretch on one court - 5-team's ten matches over two
+ * days, 3-team's three matches in one - as opposed to a 4-team group,
+ * which needs a *pair* of courts running two matches at once each
+ * round.
+ *
+ * The unit of allocation is that stretch - a run - not a match, and
+ * the day divides into as many sections as whole runs fit in it.
+ * prio.pl calls them S1 to S4; they are not clock times but the run
+ * itself, so five 45-minute matches make a 3h45 section and a 3-team
+ * group's three matches make a shorter one.
+ *
+ * Two questions have to be answered for every court, and keeping them
+ * apart is what makes the result read properly: how many runs a
+ * division holds in a section - its quota, settled up front by
+ * prepare() - and which court each of those runs lands on, which is
+ * its band, a contiguous fraction of the court list.
+ *
+ * Courts, slots, lighting and the sections themselves belong to the
+ * caller. It hands in a court and a section and gets a run back.
+ *
+ * Short groups are none of this planner's business - they are pooled
+ * across divisions onto a shared court pair.
+ *
+ * Both five-team-planner.mjs and three-team-planner.mjs are thin
+ * re-exports of this same engine - the resource model (one run, one
+ * court, whole stretch) does not change between those two shapes,
+ * only the match template (group-schedule.mjs's GROUP_TEMPLATES)
+ * enqueue() reads off the group's own team count.
+ */
+export function makeRunQueuePlanner() {
+  const groupRunQueue = new Map()
+  const sectionRunsByDivision = new Map()
+  const bandFractionByDivision = new Map()
+  const sectionQuotaByDivision = new Map()
+  const sectionCountByDate = new Map()
+  const sectionsByGroup = new Map()
+  const groupsInSection = new Set()
+  const totalRunsByDivision = new Map()
+
+  const nightSections = new Set()
+  const runLengthByDay = new Map()
+
+  /**
+   * How long one run is, in slots.
+   *
+   * Read off the runs themselves: a run is a stretch of consecutive
+   * matches on one court, so its own length is the answer. Taking one
+   * figure per competition instead meant the largest group size set
+   * the rhythm for every division in it, and a single 5-team draw made
+   * a competition of fours tick in fives.
+   */
+  function runLengthFor(competitionId, date) {
+    // Remembered as the runs are queued, not counted off the queue:
+    // by the time the plan is reported the queue has been drained,
+    // and the answer would be that a run is one slot long.
+    return runLengthByDay.get(queueKey(competitionId, date)) ?? 1
+  }
+
+  /**
+   * Queues a group's runs against the dates its competition plays.
+   *
+   * The groups arrive in division-priority order, so the strongest
+   * field claims the lowest courts, and a group's own runs stay in
+   * template order.
+   *
+   * @returns {Array<{date: string, count: number}>} the capacity the
+   *   caller still has to account for, per date.
+   */
+  function enqueue({ competition, group, dates, asFull = false }) {
+    const teams = group.team_ids ?? []
+    const size = group.pool_size ?? teams.length
+
+    // While registration is open a group is planned as the group it
+    // will be. A seat still to be filled needs the same court time as
+    // one already taken, and planning the four who have entered books
+    // a 4-team shape that the fifth then has nowhere to join. The
+    // spare cells are the point, not waste.
+    const seats = asFull && size > teams.length
+      ? Array.from({ length: size }, (_, i) => teams[i] ?? -(i + 1))
+      : teams
+
+    const runs = groupRuns({ teamIds: seats, groupSize: size })
+    const needed = []
+
+    // The days this competition is really in its group phase, not the
+    // days its draw asked for. A last group date that is also the day
+    // it turns to knockout is not a day this can use.
+    const days = dates ?? competition.group_dates ?? []
+
+    // A real, registered group with no match template at all for its
+    // actual team count (group-schedule.mjs's templateFor only covers
+    // one vacant seat, not two or more - reachable here once
+    // registration closes and asFull stops padding a short group up to
+    // its division's full size) plays nothing, silently: without this,
+    // the caller never learns it needed any games at all, so it never
+    // reaches the shortfall total either. Reported against the same
+    // "assume everyone showed up" baseline games_needed itself uses,
+    // split evenly across the group's own days like a real template's
+    // day split would be.
+    if (runs.length === 0 && seats.length > 0 && days.length > 0) {
+      const total = GAMES_PER_POOL_SIZE[size] ?? (seats.length * (seats.length - 1)) / 2
+      const perDay = Math.floor(total / days.length)
+      let remainder = total - perDay * days.length
+
+      for (const date of days) {
+        const count = perDay + (remainder > 0 ? 1 : 0)
+        remainder -= 1
+
+        if (count > 0) {
+          needed.push({ date, count })
+        }
+      }
+
+      return needed
+    }
+
+    for (const run of runs) {
+      // A template that spans two days needs two days to span. Where
+      // the competition has only one, the group plays its whole round
+      // robin that day rather than losing the half with nowhere to go
+      // - ten matches on one court, each of the five teams playing
+      // four of them. The 4-team units fold the same way when their
+      // second day turns out not to be a group day.
+      const date = days.length === 1 ? days[0] : days[run.day - 1]
+
+      if (!date) {
+        continue
+      }
+
+      const key = queueKey(competition.id, date)
+
+      if (!groupRunQueue.has(key)) {
+        groupRunQueue.set(key, [])
+      }
+
+      const divisionKey = `${date}:${group.division_id}`
+      totalRunsByDivision.set(divisionKey, (totalRunsByDivision.get(divisionKey) ?? 0) + 1)
+
+      groupRunQueue.get(key).push({
+        day: run.day,
+        isPro: group.is_pro === true,
+        groupId: group.id,
+        groupName: group.name,
+        divisionId: group.division_id,
+        divisionName: group.division_name,
+        divisionGender: group.division_gender,
+        indices: run.indices,
+        positions: run.positions,
+      })
+
+      runLengthByDay.set(key, Math.max(runLengthByDay.get(key) ?? 1, run.positions.length))
+
+      needed.push({ date, count: run.positions.length })
+    }
+
+    return needed
+  }
+
+  /**
+   * Bands and section quotas for every date that has runs queued.
+   *
+   * Worked out once, after every competition's runs are known, so they
+   * stay put as the queues drain. Reading them off the live queue made
+   * the bands drift as runs were consumed, and only the first section
+   * of the day came out in order.
+   *
+   * @param {Object} params
+   * @param {Function} params.slotsFor (competitionId, date) => the slots
+   *   that competition actually plays that day. Sizing the sections off
+   *   a shared list instead read lit_required from the server, which
+   *   leaves it unset, so a night section was counted as holding every
+   *   court when only the lit ones can host it.
+   * @param {Array} params.courts The courts these runs may use.
+   * @param {Function} params.usable (court, slot) => boolean
+   */
+  function prepare({ slotsFor, courts, usable }) {
+    for (const [key, queue] of groupRunQueue) {
+      const date = key.slice(key.indexOf(':') + 1)
+      const order = []
+
+      for (const run of queue) {
+        if (!order.includes(run.divisionId)) {
+          order.push(run.divisionId)
+        }
+      }
+
+      // How many runs each division should hold in each section of this
+      // day, worked out up front rather than emerging from the order
+      // courts happen to be filled in.
+      //
+      // Balancing incrementally could not hold both properties at once:
+      // judging every court on the running share turned a section into a
+      // round robin and interleaved the divisions, while judging it on
+      // the band let whoever owned a band take every court in it until
+      // their queue ran dry - which emptied the beginners out of S3.
+      //
+      // Deciding the counts first separates the two questions. How many
+      // runs a division gets in a section is settled here; which court
+      // each one lands on is left to the band.
+      const competitionId = key.slice(0, key.indexOf(':'))
+      const runLength = runLengthFor(competitionId, date)
+      // Only a section that can hold a whole run counts. Rounding up
+      // invented a final section out of the few slots left over, and
+      // every run shared out to it was then unplaceable.
+      const own = slotsFor(competitionId, date)
+
+      // Sections are not the same size. S1 and S2 have every court; a
+      // night section has only the lit ones, and only those that can
+      // host a whole run without the light going partway through. A flat
+      // quota therefore under-fills the day sections, the fallback fires
+      // to use the spare courts, and the balance it was meant to keep is
+      // lost.
+      const sections = sectionsFor(own, runLength, { courts, usable })
+      const sectionCount = sections.length
+      sectionCountByDate.set(date, sectionCount)
+
+      const capacities = sections.map(section => section.capacity)
+
+      for (const section of sections) {
+        if (section.night) {
+          nightSections.add(`${key}:${section.index}`)
+        }
+      }
+
+      // Capacity is shared out section by section, against what that
+      // section can hold. Slicing each division's own runs across the
+      // sections instead over-subscribed the small ones: a night section
+      // holding three runs was promising five between two divisions, so
+      // whichever was asked first took the lot and the other got none.
+      const divisions = order.filter(id => (totalRunsByDivision.get(`${date}:${id}`) ?? 0) > 0)
+
+      const totals = new Map(
+        divisions.map(id => [id, totalRunsByDivision.get(`${date}:${id}`) ?? 0])
+      )
+
+      // The quota/band math itself is shared with every other planner
+      // shape - see court-bands.mjs. Only the run-queue bookkeeping
+      // (sections, lights, offsets) stays local to this planner.
+      const { quotasBySection, bandsBySection } = computeSectionBands({
+        divisions,
+        totals,
+        capacities,
+      })
+
+      for (let section = 0; section < sectionCount; section++) {
+        for (const id of divisions) {
+          sectionQuotaByDivision.set(`${date}:${section}:${id}`, quotasBySection[section].get(id))
+          bandFractionByDivision.set(`${date}:${section}:${id}`, bandsBySection[section].get(id))
+        }
+      }
+    }
+  }
+
+  /**
+   * Night capacity is the scarce resource, and taking runs in strict
+   * division order let the top division drain it - the strongest field
+   * played every night game and three divisions played none at all.
+   *
+   * The next run goes to whichever division would end up with the
+   * smallest share of its own runs in this section - prio.pl's S1 to
+   * S4, which are not clock times but the run itself: a section is one
+   * group's whole run on one court, so five 45-minute matches make a
+   * 3h45 section and a 4-team group's three make a shorter one.
+   *
+   * Balancing per section spreads every division across the day rather
+   * than letting the first division fill the morning and the last take
+   * whatever is left. Weighting by share rather than by count keeps it
+   * proportional: half the games means half the runs in each section.
+   *
+   * The +0.5 divisor is deliberate. Comparing the share a division
+   * already holds lets a small division jump the queue every time and
+   * finish over its proportion; plain +1 biases the other way, toward
+   * the large ones.
+   *
+   * Ties fall to the queue order, which is division priority, so the
+   * strongest field takes the lowest-numbered courts.
+   */
+  function sectionCountFor(date) {
+    return sectionCountByDate.get(date) ?? 1
+  }
+
+  function pick(competitionId, date, sectionIndex, court, { proCourt = false } = {}) {
+    const queue = groupRunQueue.get(queueKey(competitionId, date))
+
+    if (!queue || queue.length === 0) {
+      return null
+    }
+
+    // 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. Singles
+    // carries both kinds, so asking the competition put the beginners
+    // on the pro courts and left the pro draws queueing behind them.
+    const belongs = run => (run.isPro === true) === proCourt
+
+    if (!queue.some(belongs)) {
+      return { blocked: true }
+    }
+
+    // Where along the courts this one sits, so a run can be judged on
+    // how well it belongs here.
+    const position = court && court.courtCount > 0
+      ? court.courtPosition / court.courtCount
+      : 0
+
+    const scored = queue.map(run => {
+      const key = `${date}:${sectionIndex}:${run.divisionId}`
+      const used = sectionRunsByDivision.get(key) ?? 0
+      const total = totalRunsByDivision.get(`${date}:${run.divisionId}`) ?? 1
+
+      // The share this division would hold after taking the run, not
+      // the one it holds now. Comparing current shares lets a small
+      // division jump the queue on every pick and finish over its
+      // proportion - a division with half the games took six evenings
+      // where five was its share.
+      const share = (used + 0.5) / total
+
+      // Whether this court falls inside the division's own band, and
+      // if not how far outside. A band is an interval, not a point:
+      // measuring from its start alone hands the wider division too
+      // few courts, since every court is near some band's start.
+      const band = bandFractionByDivision.get(`${date}:${sectionIndex}:${run.divisionId}`)
+        ?? { start: 0, end: 1 }
+      const distance = bandDistance(position, band)
+
+      return { share, step: 1 / total, distance }
+    })
+
+    // Share decides who is owed a run, the band decides where it goes.
+    //
+    // Neither alone works. Sorting on share first turns the section
+    // into a round robin and interleaves the divisions across the
+    // courts. Sorting on the band first lets whoever owns a band take
+    // every court in it until their queue runs dry, which emptied the
+    // beginners out of S3 entirely.
+    //
+    // The tolerance is one run's worth of share, so a division that
+    // has just taken a court is still owed enough to take the one next
+    // to it, and its groups stay together without it running away with
+    // the section.
+    // The quota decides who is owed a run in this section; the band
+    // decides which court it lands on. A division that has filled its
+    // quota here stands aside, so nobody runs away with a section, and
+    // among those still owed a run the court goes to whichever
+    // division's band covers it.
+    const indexed = scored
+      .map((entry, index) => ({ ...entry, index }))
+      .filter(entry => belongs(queue[entry.index]))
+
+    // A group that played under lights yesterday is not asked to do it
+    // again. This one is a rule rather than a preference: back-to-back
+    // late finishes are what the rotation exists to prevent.
+    const eligible = night(competitionId, date, sectionIndex)
+      ? indexed.filter(entry => !playedUnderLights(queue[entry.index].groupId, date))
+      : indexed
+
+    // If every run left belongs to a group that played under lights
+    // yesterday, this court goes unused. Leaving a lit court idle is
+    // the lesser harm: the rotation exists precisely to stop the same
+    // group finishing late twice running. Distinct from a null return,
+    // which means there is nothing left to place at all.
+    if (eligible.length === 0) {
+      return { blocked: true }
+    }
+
+    // A group plays one run at a time. Where one group day holds a
+    // whole two-day template both halves sit in the same queue, and
+    // without this the second was handed the court beside the first -
+    // five teams playing ten matches two at a time, every one of them
+    // double-booked.
+    const free = eligible.filter(
+      entry => !groupsInSection.has(`${date}:${sectionIndex}:${queue[entry.index].groupId}`)
+    )
+
+    if (free.length === 0) {
+      return { blocked: true }
+    }
+
+    // Nor does any group start its second run until every group has
+    // had its first, or one would take the day while another sat out.
+    const earliest = Math.min(...free.map(entry => queue[entry.index].day ?? 1))
+    const pool = free.filter(entry => (queue[entry.index].day ?? 1) === earliest)
+
+    const owed = pool.filter(entry => {
+      const key = `${date}:${sectionIndex}:${queue[entry.index].divisionId}`
+      const quota = sectionQuotaByDivision.get(key) ?? Infinity
+
+      return (sectionRunsByDivision.get(key) ?? 0) < quota
+    })
+
+    // Rounding, or a section with more room than its quotas asked for,
+    // can leave nobody owed. The run still has to go somewhere rather
+    // than leave a court idle - but the spare capacity goes to whoever
+    // is furthest behind overall, not to whichever division's band
+    // happens to cover the leftover courts. Sorting the overflow by
+    // band handed every spare court in S1 to one division and emptied
+    // it out of S2.
+    // Of those still owed a run here, prefer the groups this section
+    // is the offset of - S3 wants yesterday's S1, S1 wants yesterday's
+    // S3. Guidance rather than a rule: there is rarely room to honour
+    // it for every group, so it only orders the choice.
+    const wanted = owed.filter(entry => {
+      const previous = previousSection(queue[entry.index].groupId, date)
+      return previous !== null && SECTION_OFFSET[previous] === sectionIndex
+    })
+
+    // Failing the exact rotation, anything but the same section again.
+    // A group's offset target is often a night section with no room
+    // left, and without this it simply stayed where it was - half the
+    // groups repeating S2 two days running.
+    const moved = owed.filter(entry => {
+      const previous = previousSection(queue[entry.index].groupId, date)
+      return previous === null || previous !== sectionIndex
+    })
+
+    const wantedSet = new Set(wanted)
+    const movedSet = new Set(moved)
+
+    const best = owed.length > 0
+      ? owed.reduce((a, b) => {
+        // The band comes first, always - which court a division holds
+        // is what keeps its groups together. The offset only chooses
+        // between two divisions that fit this court equally well; it
+        // never pulls a division away from a court its own band
+        // already covers in favour of one merely due its rotation.
+        // Treating "wanted" as a hard filter did exactly that: a
+        // division sitting at distance 0 lost the court to one at
+        // distance 0.121 purely because the latter was due its S3-to-
+        // S1 offset, splitting the first division's band in two.
+        if (b.distance !== a.distance) {
+          return b.distance < a.distance ? b : a
+        }
+
+        const aWanted = wantedSet.has(a)
+        const bWanted = wantedSet.has(b)
+
+        if (aWanted !== bWanted) {
+          return bWanted ? b : a
+        }
+
+        const aMoved = movedSet.has(a)
+        const bMoved = movedSet.has(b)
+
+        if (aMoved !== bMoved) {
+          return bMoved ? b : a
+        }
+
+        return b.share < a.share ? b : a
+      })
+      : (() => {
+        // Spare capacity, beyond what the quotas asked for. It still
+        // must not eat a division's later sections: one with four runs
+        // and four sections has exactly one for each, and taking two
+        // here leaves it absent from the last.
+        // Spare capacity, beyond what the quotas asked for. A
+        // division may take it only if it will still have a run left
+        // for every section after this one - otherwise an extra court
+        // now costs it its place later in the day.
+        const sectionsLeft = Math.max(0, sectionCountFor(date) - sectionIndex - 1)
+
+        const canSpare = pool.filter(entry => {
+          const division = queue[entry.index].divisionId
+          const queued = queue.filter(run => run.divisionId === division).length
+
+          return queued - 1 >= sectionsLeft
+        })
+
+        // Nobody can take it without stranding themselves, so the
+        // court stays free - it was spare to begin with.
+        if (canSpare.length === 0) {
+          return { blocked: true }
+        }
+
+        const candidates = canSpare
+
+        // Among those equally far behind, the court still goes to
+        // whichever division's band covers it, so the leftover courts
+        // at the top of a section join the division already sitting
+        // there instead of dragging one up from the bottom.
+        const behind = Math.min(...candidates.map(entry => entry.share))
+        const slack = Math.max(...candidates.map(entry => entry.step))
+
+        return candidates
+          .filter(entry => entry.share <= behind + slack)
+          .reduce((a, b) => (b.distance < a.distance ? b : a))
+      })()
+
+    if (!best) {
+      return { blocked: true }
+    }
+
+    return { run: queue[best.index], index: best.index }
+  }
+
+  /**
+   * Taking the run is separate from choosing it: the court is picked
+   * to suit the run's division, and if no court can host it the run
+   * has to stay in the queue for a later slot.
+   */
+  function commit(competitionId, date, sectionIndex, index) {
+    const queue = groupRunQueue.get(queueKey(competitionId, date))
+    const [run] = queue.splice(index, 1)
+    const key = `${date}:${sectionIndex}:${run.divisionId}`
+
+    sectionRunsByDivision.set(key, (sectionRunsByDivision.get(key) ?? 0) + 1)
+    groupsInSection.add(`${date}:${sectionIndex}:${run.groupId}`)
+
+    // What this group played today, so tomorrow can be offset from it.
+    const history = sectionsByGroup.get(run.groupId) ?? []
+    history.push({
+      date,
+      section: sectionIndex,
+      night: night(competitionId, date, sectionIndex),
+    })
+    sectionsByGroup.set(run.groupId, history)
+
+    return run
+  }
+
+  /**
+   * Whether a section is played under lights.
+   *
+   * Asked per competition and date, never by section number alone.
+   * Competitions do not share a clock: one starting at 16:30 has its
+   * section 1 after dark while one starting at 08:00 has its at 11:00,
+   * so a bare index let one competition's evening bar every other
+   * competition's morning.
+   */
+  function night(competitionId, date, section) {
+    return nightSections.has(`${queueKey(competitionId, date)}:${section}`)
+  }
+
+  /**
+   * Whether a group finished under lights on the day it last played.
+   * Recorded when the run was taken, because a section number on its
+   * own says nothing about the hour it falls in.
+   */
+  function playedUnderLights(groupId, date) {
+    const earlier = (sectionsByGroup.get(groupId) ?? []).filter(entry => entry.date < date)
+
+    return earlier.length > 0 && earlier[earlier.length - 1].night === true
+  }
+
+  /**
+   * The section a group played most recently before this date.
+   */
+  function previousSection(groupId, date) {
+    const history = sectionsByGroup.get(groupId) ?? []
+    const earlier = history.filter(entry => entry.date < date)
+
+    return earlier.length === 0 ? null : earlier[earlier.length - 1].section
+  }
+
+  /**
+   * Every competition and date that has runs queued, so the caller can
+   * work out each one's sections before play is laid out.
+   */
+  function queued() {
+    return [...groupRunQueue.keys()].map(key => ({
+      competitionId: key.slice(0, key.indexOf(':')),
+      date: key.slice(key.indexOf(':') + 1),
+    }))
+  }
+
+  /**
+   * Whether this competition/date has any runs of this planner's own
+   * shape still to place. A caller juggling more than one run-queue
+   * planner (5-team groups and 3-team groups both feed a run-queue,
+   * but from separate instances) uses this to ask which one actually
+   * owns a given competition's day, rather than guessing.
+   */
+  function hasQueued(competitionId, date) {
+    const queue = groupRunQueue.get(queueKey(competitionId, date))
+
+    return (queue?.length ?? 0) > 0
+  }
+
+  return { enqueue, prepare, pick, commit, previousSection, queued, hasQueued, runLengthFor }
+}

package/lib/sessions.mjs

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Whichever session most recently started (on or before this date and
+ * hour) determines the active phase - null if no session has started
+ * yet.
+ */
+export function activePhase(sessions, date, hour) {
+  let active = null
+
+  for (const session of sessions) {
+    const started = session.date === date && session.start_time <= hour
+
+    if (session.date < date || started) {
+      active = session.phase
+    } else {
+      break
+    }
+  }
+
+  return active
+}
+/**
+ * The slots a competition runs on a date.
+ *
+ * Its active session says when play starts and how long a match is, so
+ * the slots are that start time and one every playtime minutes after.
+ * There is no shared grid: doubles opens at 08:00 in 45-minute matches
+ * while Team Cup opens at 09:00 in 90-minute ones, and no single ruler
+ * measures both.
+ *
+ * @param {Array<{date: string, start_time: string, playtime: ?number,
+ *   phase: string}>} sessions
+ *   in date order
+ */
+export function activeSession(sessions, date) {
+  let active = null
+
+  for (const session of sessions) {
+    if (session.date <= date) {
+      active = session
+    }
+  }
+
+  return active
+}