volleyballsimtypes 0.0.491 → 0.0.492

package/dist/esm/src/service/competition/event-rewards.test.js

@@ -0,0 +1,56 @@
+import { describe, it, expect } from '@jest/globals';
+import { EVENT_REWARDS, eventPayoutFor, eventRewardBandFor } from './event-rewards';
+describe('eventRewardBandFor()', () => {
+    it.each([
+        [1, 'TOP_1'],
+        [2, 'TOP_3'],
+        [3, 'TOP_3'],
+        [4, 'TOP_5'],
+        [5, 'TOP_5'],
+        [6, 'TOP_10'],
+        [10, 'TOP_10'],
+        [11, 'TOP_20'],
+        [20, 'TOP_20'],
+        // Inside a 24-team final but outside every banded row, so it counts as taking part.
+        [21, 'PARTICIPATION'],
+        [24, 'PARTICIPATION']
+    ])('places a finish of %i in %s', (position, band) => {
+        expect(eventRewardBandFor(position)).toBe(band);
+    });
+    it('treats a team that never reached the final as participation', () => {
+        expect(eventRewardBandFor(null)).toBe('PARTICIPATION');
+    });
+});
+describe('eventPayoutFor()', () => {
+    it.each([
+        // position, packs, coins. Cumulative: every row from Participation down to the finish.
+        [null, 1, 1000], // group stage: 1 pack + 1000
+        [24, 1, 1000], // in the final but outside the top 20: still just participation
+        [20, 1, 2000], // + top 20's 1000
+        [11, 1, 2000],
+        [10, 2, 2000], // + top 10's pack
+        [6, 2, 2000],
+        [5, 2, 3000], // + top 5's 1000
+        [4, 2, 3000],
+        [3, 2, 3500], // + top 3's 500
+        [2, 2, 3500],
+        [1, 3, 3500] // + the winner's pack
+    ])('pays a finish of %s with %i packs and %i coins', (position, packs, coins) => {
+        expect(eventPayoutFor(position)).toEqual({ packs, coins });
+    });
+    it('never pays less for a better finish', () => {
+        const finishes = [null, 24, 20, 11, 10, 6, 5, 4, 3, 2, 1];
+        for (let i = 1; i < finishes.length; i++) {
+            const worse = eventPayoutFor(finishes[i - 1]);
+            const better = eventPayoutFor(finishes[i]);
+            expect(better.packs).toBeGreaterThanOrEqual(worse.packs);
+            expect(better.coins).toBeGreaterThanOrEqual(worse.coins);
+        }
+    });
+    it('adds up to the owner-defined table for a winner', () => {
+        // 1x pack + 1000 (participation), +1000 (top 20), +1 pack (top 10), +1000 (top 5), +500 (top 3), +1 pack (top 1)
+        const total = EVENT_REWARDS.reduce((acc, row) => ({ packs: acc.packs + row.packs, coins: acc.coins + row.coins }), { packs: 0, coins: 0 });
+        expect(eventPayoutFor(1)).toEqual(total);
+        expect(total).toEqual({ packs: 3, coins: 3500 });
+    });
+});

package/dist/esm/src/service/competition/event-schedule.d.ts

@@ -0,0 +1,126 @@
+import { Rarity } from '../player';
+export type EventKey = 'WAR_OF_THE_COMMONS' | 'RARE_GEMS' | 'STUFF_OF_LEGENDS';
+/**
+ * How an event is played out. One member today; a new format is a new member here AND the code path in the
+ * simulator that builds its schedule, which is why formats live in code rather than in a table.
+ * - `GROUPS_FINAL` equal groups playing a round robin, then one final group of the qualifiers on the last day.
+ */
+export type EventFormat = 'GROUPS_FINAL';
+/**
+ * Where an event is in its life.
+ * - `REGISTRATION` the lineup can be saved; saving is what registers the team.
+ * - `IN_PROGRESS`  matches are scheduled and playing (group stage, then the final).
+ * - `REVIEW`       finished; results readable, nothing playing.
+ * - `ARCHIVED`     purged; only the Event row itself survives.
+ */
+export type EventStatus = 'REGISTRATION' | 'IN_PROGRESS' | 'REVIEW' | 'ARCHIVED';
+/**
+ * A preset: everything about HOW an event works. An admin cannot change any of it, they pick one of these and
+ * say when it starts, so an event can never be configured into a shape the simulator cannot run.
+ */
+export interface EventDefinition {
+    readonly key: EventKey;
+    readonly format: EventFormat;
+    /** Every player referenced anywhere in the event lineup must be EXACTLY this rarity. */
+    readonly rarity: Rarity;
+    /** Total days from the start, the last of which is the final. */
+    readonly durationDays: number;
+}
+export declare const EVENT_CATALOGUE: readonly EventDefinition[];
+/** An event must be long enough to hold a group stage AND a final day. */
+export declare const MIN_DURATION_DAYS = 2;
+/** Registration has to give players a real chance to build a squad, and cannot be scheduled absurdly far out. */
+export declare const MIN_REGISTRATION_DAYS = 1;
+export declare const MAX_REGISTRATION_DAYS = 30;
+/** Results stay readable for this long after an event ends, then everything but the Event row is deleted. */
+export declare const REVIEW_DAYS = 3;
+/**
+ * The final group is 24 teams: at one match per hour that is 23 rounds, which is the largest round robin that
+ * still fits inside the single final day.
+ */
+export declare const MAX_FINAL_SIZE = 24;
+/** A group is padded with bots to at least this many teams, so a small turnout still plays a real group stage. */
+export declare const MIN_GROUP_SIZE = 16;
+/** Rounds are never closer together than an hour, which is what bounds how large a group can be. */
+export declare const MIN_ROUND_SPACING_MINUTES = 60;
+/** One match per hour in the final: 24 teams = 23 rounds, 00:00 to 23:00. */
+export declare const FINAL_ROUND_SPACING_MINUTES = 60;
+/**
+ * How a turnout is split into groups, and how many of each group go through.
+ *
+ * Owner-defined (2026-07-23). Read as "fewer than `maxParticipants`". Every row multiplies out to exactly
+ * MAX_FINAL_SIZE, so the final is always 24 teams however many entered, and every group sends the same number
+ * through. Group counts that cannot divide 24 into whole qualifiers (5, 10) are deliberately absent.
+ */
+export interface EventGroupTier {
+    /** Exclusive upper bound on the entrant count for this tier. */
+    readonly maxParticipants: number;
+    readonly groupCount: number;
+    readonly qualifiersPerGroup: number;
+}
+export declare const EVENT_GROUP_TIERS: readonly EventGroupTier[];
+/** The tier a turnout falls into. The last row has no upper bound, so this always resolves. */
+export declare function eventGroupTierFor(participantCount: number): EventGroupTier;
+/** The preset a stored event was created from. Its rules are read from this, never re-derived. */
+export declare function eventDefinitionForKey(key: EventKey): EventDefinition;
+export interface EventWindows {
+    readonly key: EventKey;
+    readonly format: EventFormat;
+    readonly rarity: Rarity;
+    /** Registration opens this many days before the start. */
+    readonly registrationOpensAt: Date;
+    /** Registration closes the instant the event starts. */
+    readonly registrationClosesAt: Date;
+    readonly startsAt: Date;
+    /** 00:00 UTC on the last day: the final is a single day, one round per hour. */
+    readonly finalStartsAt: Date;
+    /** The exclusive end of the last day. */
+    readonly endsAt: Date;
+    /** Review ends and everything but the Event row is deleted. */
+    readonly purgeAt: Date;
+}
+/**
+ * Every date an event will ever have, computed once from its preset, its start day and how much lead time
+ * registration gets. The start is floored to 00:00 UTC so an event always runs whole days.
+ *
+ * ```
+ * start - registrationDays   registration opens
+ * start                      registration closes, group stage begins
+ * start + duration - 1       the final (one day)
+ * start + duration           the event ends, review begins
+ * start + duration + 3       purge
+ * ```
+ */
+export declare function eventWindowsFor(definition: EventDefinition, startsAt: Date, registrationDays: number): EventWindows;
+/** How long the group stage has, in hours: everything before the final day. */
+export declare function groupStageHours(definition: EventDefinition): number;
+export declare function eventStatusAt(windows: EventWindows, now: Date): EventStatus;
+export interface EventGroupPlan {
+    readonly groupCount: number;
+    /** Equal across every group, always even, bots making up the difference. */
+    readonly groupSize: number;
+    /** How many bot teams have to be generated to fill the groups. */
+    readonly botCount: number;
+    readonly qualifiersPerGroup: number;
+    readonly finalSize: number;
+    /** Minutes between group-stage rounds, so the whole round robin lands inside the group-stage window. */
+    readonly groupRoundSpacingMinutes: number;
+    /** True when the group stage cannot fit even at the minimum spacing; the caller must log it loudly. */
+    readonly overflows: boolean;
+}
+/**
+ * Rounds start on the hour or the half hour and nothing else, so a kickoff never reads as 19:12.
+ *
+ * Snapped DOWN, so a stage that already fits its window still fits: rounding up could push the last round past
+ * the final. Events start at 00:00 UTC, so every round lands on the grid.
+ */
+export declare const ROUND_SPACING_GRID_MINUTES = 30;
+/**
+ * How a turnout of `participantCount` real teams is split, and how the round robin is paced to fit
+ * `stageHours` (the event's days before its final day, from groupStageHours).
+ *
+ * The group count and the number that go through come from EVENT_GROUP_TIERS. Groups are all equal in size,
+ * always even (a round robin needs an even field for everyone to play every round) and bot-padded to at least
+ * MIN_GROUP_SIZE, so a small turnout still plays a full group stage.
+ */
+export declare function planEventGroups(participantCount: number, stageHours: number): EventGroupPlan;

package/dist/esm/src/service/competition/event-schedule.js

@@ -0,0 +1,129 @@
+import dayjs from 'dayjs';
+import utc from 'dayjs/plugin/utc';
+import { RarityEnum } from '../player';
+dayjs.extend(utc);
+// The presets an admin can schedule. Adding one here (plus its name in the 7 locale files) is all a new event
+// needs, as long as its format is one the simulator already builds.
+export const EVENT_CATALOGUE = [
+    { key: 'WAR_OF_THE_COMMONS', format: 'GROUPS_FINAL', rarity: RarityEnum.COMMON, durationDays: 7 },
+    { key: 'RARE_GEMS', format: 'GROUPS_FINAL', rarity: RarityEnum.RARE, durationDays: 7 },
+    { key: 'STUFF_OF_LEGENDS', format: 'GROUPS_FINAL', rarity: RarityEnum.LEGENDARY, durationDays: 7 }
+];
+/** An event must be long enough to hold a group stage AND a final day. */
+export const MIN_DURATION_DAYS = 2;
+/** Registration has to give players a real chance to build a squad, and cannot be scheduled absurdly far out. */
+export const MIN_REGISTRATION_DAYS = 1;
+export const MAX_REGISTRATION_DAYS = 30;
+/** Results stay readable for this long after an event ends, then everything but the Event row is deleted. */
+export const REVIEW_DAYS = 3;
+/**
+ * The final group is 24 teams: at one match per hour that is 23 rounds, which is the largest round robin that
+ * still fits inside the single final day.
+ */
+export const MAX_FINAL_SIZE = 24;
+/** A group is padded with bots to at least this many teams, so a small turnout still plays a real group stage. */
+export const MIN_GROUP_SIZE = 16;
+/** Rounds are never closer together than an hour, which is what bounds how large a group can be. */
+export const MIN_ROUND_SPACING_MINUTES = 60;
+/** One match per hour in the final: 24 teams = 23 rounds, 00:00 to 23:00. */
+export const FINAL_ROUND_SPACING_MINUTES = 60;
+export const EVENT_GROUP_TIERS = [
+    { maxParticipants: 64, groupCount: 3, qualifiersPerGroup: 8 },
+    { maxParticipants: 96, groupCount: 4, qualifiersPerGroup: 6 },
+    { maxParticipants: 128, groupCount: 6, qualifiersPerGroup: 4 },
+    { maxParticipants: 192, groupCount: 8, qualifiersPerGroup: 3 },
+    { maxParticipants: Number.POSITIVE_INFINITY, groupCount: 12, qualifiersPerGroup: 2 }
+];
+/** The tier a turnout falls into. The last row has no upper bound, so this always resolves. */
+export function eventGroupTierFor(participantCount) {
+    return EVENT_GROUP_TIERS.find(tier => participantCount < tier.maxParticipants) ?? EVENT_GROUP_TIERS[EVENT_GROUP_TIERS.length - 1];
+}
+/** The preset a stored event was created from. Its rules are read from this, never re-derived. */
+export function eventDefinitionForKey(key) {
+    const definition = EVENT_CATALOGUE.find(e => e.key === key);
+    if (definition == null)
+        throw new Error(`UNKNOWN_EVENT_KEY: ${key}`);
+    return definition;
+}
+/**
+ * Every date an event will ever have, computed once from its preset, its start day and how much lead time
+ * registration gets. The start is floored to 00:00 UTC so an event always runs whole days.
+ *
+ * ```
+ * start - registrationDays   registration opens
+ * start                      registration closes, group stage begins
+ * start + duration - 1       the final (one day)
+ * start + duration           the event ends, review begins
+ * start + duration + 3       purge
+ * ```
+ */
+export function eventWindowsFor(definition, startsAt, registrationDays) {
+    const start = dayjs.utc(startsAt).startOf('day');
+    return {
+        key: definition.key,
+        format: definition.format,
+        rarity: definition.rarity,
+        registrationOpensAt: start.subtract(registrationDays, 'day').toDate(),
+        registrationClosesAt: start.toDate(),
+        startsAt: start.toDate(),
+        finalStartsAt: start.add(definition.durationDays - 1, 'day').toDate(),
+        endsAt: start.add(definition.durationDays, 'day').toDate(),
+        purgeAt: start.add(definition.durationDays + REVIEW_DAYS, 'day').toDate()
+    };
+}
+/** How long the group stage has, in hours: everything before the final day. */
+export function groupStageHours(definition) {
+    return (definition.durationDays - 1) * 24;
+}
+export function eventStatusAt(windows, now) {
+    const t = now.getTime();
+    if (t < windows.startsAt.getTime())
+        return 'REGISTRATION';
+    if (t < windows.endsAt.getTime())
+        return 'IN_PROGRESS';
+    if (t < windows.purgeAt.getTime())
+        return 'REVIEW';
+    return 'ARCHIVED';
+}
+function evenUp(n) {
+    return n % 2 === 0 ? n : n + 1;
+}
+/**
+ * Rounds start on the hour or the half hour and nothing else, so a kickoff never reads as 19:12.
+ *
+ * Snapped DOWN, so a stage that already fits its window still fits: rounding up could push the last round past
+ * the final. Events start at 00:00 UTC, so every round lands on the grid.
+ */
+export const ROUND_SPACING_GRID_MINUTES = 30;
+function snapToGrid(minutes) {
+    return Math.floor(minutes / ROUND_SPACING_GRID_MINUTES) * ROUND_SPACING_GRID_MINUTES;
+}
+/**
+ * How a turnout of `participantCount` real teams is split, and how the round robin is paced to fit
+ * `stageHours` (the event's days before its final day, from groupStageHours).
+ *
+ * The group count and the number that go through come from EVENT_GROUP_TIERS. Groups are all equal in size,
+ * always even (a round robin needs an even field for everyone to play every round) and bot-padded to at least
+ * MIN_GROUP_SIZE, so a small turnout still plays a full group stage.
+ */
+export function planEventGroups(participantCount, stageHours) {
+    const tier = eventGroupTierFor(participantCount);
+    const groupCount = tier.groupCount;
+    const groupSize = Math.max(MIN_GROUP_SIZE, evenUp(Math.ceil(participantCount / groupCount)));
+    // Capped by the group size purely as a guard; with a 16-team minimum and at most 8 going through it never binds.
+    const qualifiersPerGroup = Math.min(tier.qualifiersPerGroup, groupSize);
+    // One round per pairing: an even group plays groupSize-1 rounds, spread across the whole group-stage window.
+    const rounds = groupSize - 1;
+    const spacing = Math.floor((stageHours * 60) / rounds);
+    return {
+        groupCount,
+        groupSize,
+        botCount: groupCount * groupSize - participantCount,
+        qualifiersPerGroup,
+        finalSize: qualifiersPerGroup * groupCount,
+        groupRoundSpacingMinutes: Math.max(MIN_ROUND_SPACING_MINUTES, snapToGrid(spacing)),
+        // Judged on the UNSNAPPED spacing: snapping only ever shortens the gap, so it cannot rescue a stage that
+        // already does not fit, and judging the snapped value would hide a genuine overflow.
+        overflows: spacing < MIN_ROUND_SPACING_MINUTES
+    };
+}

package/dist/esm/src/service/competition/event-schedule.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/service/competition/event-schedule.test.js

@@ -0,0 +1,136 @@
+import { describe, it, expect } from '@jest/globals';
+import { EVENT_CATALOGUE, MAX_FINAL_SIZE, MIN_GROUP_SIZE, MIN_ROUND_SPACING_MINUTES, REVIEW_DAYS, eventDefinitionForKey, eventStatusAt, eventWindowsFor, groupStageHours, planEventGroups } from './event-schedule';
+import { RarityEnum } from '../player';
+const COMMONS = eventDefinitionForKey('WAR_OF_THE_COMMONS');
+describe('EVENT_CATALOGUE', () => {
+    it('restricts the three launch presets to a single rarity each, over one week', () => {
+        expect(EVENT_CATALOGUE.map(e => e.rarity)).toEqual([RarityEnum.COMMON, RarityEnum.RARE, RarityEnum.LEGENDARY]);
+        expect(EVENT_CATALOGUE.every(e => e.durationDays === 7)).toBe(true);
+        expect(EVENT_CATALOGUE.every(e => e.format === 'GROUPS_FINAL')).toBe(true);
+    });
+    it('leaves room for a final day in every preset', () => {
+        expect(EVENT_CATALOGUE.every(e => e.durationDays >= 2)).toBe(true);
+    });
+});
+describe('eventDefinitionForKey()', () => {
+    it('reads the rules off the key an event stores', () => {
+        expect(eventDefinitionForKey('STUFF_OF_LEGENDS').rarity).toBe(RarityEnum.LEGENDARY);
+        expect(eventDefinitionForKey('RARE_GEMS').rarity).toBe(RarityEnum.RARE);
+        expect(eventDefinitionForKey('WAR_OF_THE_COMMONS').rarity).toBe(RarityEnum.COMMON);
+    });
+    it('throws on a key that is not in the catalogue', () => {
+        expect(() => eventDefinitionForKey('NOT_AN_EVENT')).toThrow('UNKNOWN_EVENT_KEY');
+    });
+});
+describe('eventWindowsFor()', () => {
+    it('derives every date from the preset, the start day and the registration lead time', () => {
+        const w = eventWindowsFor(COMMONS, new Date('2026-08-03T00:00:00.000Z'), 4);
+        expect(w.registrationOpensAt.toISOString()).toBe('2026-07-30T00:00:00.000Z'); // start - 4 days
+        expect(w.registrationClosesAt.toISOString()).toBe('2026-08-03T00:00:00.000Z'); // = startsAt
+        expect(w.startsAt.toISOString()).toBe('2026-08-03T00:00:00.000Z');
+        expect(w.finalStartsAt.toISOString()).toBe('2026-08-09T00:00:00.000Z'); // last day of 7
+        expect(w.endsAt.toISOString()).toBe('2026-08-10T00:00:00.000Z');
+        expect(w.purgeAt.toISOString()).toBe('2026-08-13T00:00:00.000Z'); // + 3 review days
+    });
+    it('floors the start to 00:00 UTC so an event always runs whole days', () => {
+        const w = eventWindowsFor(COMMONS, new Date('2026-08-03T17:42:11.000Z'), 4);
+        expect(w.startsAt.toISOString()).toBe('2026-08-03T00:00:00.000Z');
+    });
+    it('moves registration with the lead time and nothing else', () => {
+        const a = eventWindowsFor(COMMONS, new Date('2026-08-03T00:00:00.000Z'), 1);
+        const b = eventWindowsFor(COMMONS, new Date('2026-08-03T00:00:00.000Z'), 14);
+        expect(a.registrationOpensAt.toISOString()).toBe('2026-08-02T00:00:00.000Z');
+        expect(b.registrationOpensAt.toISOString()).toBe('2026-07-20T00:00:00.000Z');
+        expect(a.startsAt.getTime()).toBe(b.startsAt.getTime());
+        expect(a.endsAt.getTime()).toBe(b.endsAt.getTime());
+        expect(a.purgeAt.getTime()).toBe(b.purgeAt.getTime());
+    });
+    it('gives the final exactly one day, whatever the duration', () => {
+        for (const durationDays of [2, 3, 7, 10]) {
+            const w = eventWindowsFor({ ...COMMONS, durationDays }, new Date('2026-08-03T00:00:00.000Z'), 4);
+            expect(w.endsAt.getTime() - w.finalStartsAt.getTime()).toBe(24 * 3600 * 1000);
+            expect(w.endsAt.getTime() - w.startsAt.getTime()).toBe(durationDays * 24 * 3600 * 1000);
+            expect(w.purgeAt.getTime() - w.endsAt.getTime()).toBe(REVIEW_DAYS * 24 * 3600 * 1000);
+        }
+    });
+});
+describe('groupStageHours()', () => {
+    it('is every day before the final day', () => {
+        expect(groupStageHours({ ...COMMONS, durationDays: 7 })).toBe(144);
+        expect(groupStageHours({ ...COMMONS, durationDays: 2 })).toBe(24);
+        expect(groupStageHours({ ...COMMONS, durationDays: 10 })).toBe(216);
+    });
+});
+describe('eventStatusAt()', () => {
+    const w = eventWindowsFor(COMMONS, new Date('2026-08-03T00:00:00.000Z'), 4);
+    it.each([
+        ['2026-07-30T00:00:00.000Z', 'REGISTRATION'],
+        ['2026-08-02T23:59:59.000Z', 'REGISTRATION'],
+        ['2026-08-03T00:00:00.000Z', 'IN_PROGRESS'],
+        ['2026-08-09T12:00:00.000Z', 'IN_PROGRESS'],
+        ['2026-08-09T23:59:59.000Z', 'IN_PROGRESS'],
+        ['2026-08-10T00:00:00.000Z', 'REVIEW'],
+        ['2026-08-12T23:59:59.000Z', 'REVIEW'],
+        ['2026-08-13T00:00:00.000Z', 'ARCHIVED']
+    ])('reads %s as %s', (iso, status) => {
+        expect(eventStatusAt(w, new Date(iso))).toBe(status);
+    });
+});
+describe('planEventGroups()', () => {
+    const WEEK = groupStageHours(COMMONS); // 144h, the six days before the final
+    it.each([
+        // turnout, groups, size, qualifiers/group, final. Tiers: <64 = 3 groups top 8, <96 = 4 top 6,
+        // <128 = 6 top 4, <192 = 8 top 3, otherwise 12 top 2. Every tier multiplies out to a 24-team final.
+        [1, 3, MIN_GROUP_SIZE, 8, 24],
+        [12, 3, MIN_GROUP_SIZE, 8, 24],
+        [48, 3, MIN_GROUP_SIZE, 8, 24],
+        [63, 3, 22, 8, 24],
+        [64, 4, MIN_GROUP_SIZE, 6, 24],
+        [95, 4, 24, 6, 24],
+        [96, 6, MIN_GROUP_SIZE, 4, 24],
+        [127, 6, 22, 4, 24],
+        [128, 8, MIN_GROUP_SIZE, 3, 24],
+        [191, 8, 24, 3, 24],
+        [192, 12, MIN_GROUP_SIZE, 2, 24],
+        [300, 12, 26, 2, 24]
+    ])('splits a turnout of %i into %i groups of %i', (n, groupCount, groupSize, qualifiersPerGroup, finalSize) => {
+        const plan = planEventGroups(n, WEEK);
+        expect(plan.groupCount).toBe(groupCount);
+        expect(plan.groupSize).toBe(groupSize);
+        expect(plan.qualifiersPerGroup).toBe(qualifiersPerGroup);
+        expect(plan.finalSize).toBe(finalSize);
+        expect(plan.botCount).toBe(groupCount * groupSize - n);
+    });
+    it.each([1, 2, 7, 12, 33, 40, 41, 60, 61, 99, 100, 137, 250, 500])('keeps every group even, bot-padded and inside the final cap for a turnout of %i', (n) => {
+        const plan = planEventGroups(n, WEEK);
+        expect(plan.groupSize % 2).toBe(0); // even, so nobody sits a group-stage round out
+        expect(plan.groupSize).toBeGreaterThanOrEqual(MIN_GROUP_SIZE);
+        expect([3, 4, 6, 8, 12]).toContain(plan.groupCount);
+        expect(plan.botCount).toBeGreaterThanOrEqual(0);
+        expect(plan.groupCount * plan.groupSize).toBe(n + plan.botCount);
+        // Every tier is built to fill the final exactly, however many entered.
+        expect(plan.finalSize).toBe(MAX_FINAL_SIZE);
+        expect(plan.finalSize % 2).toBe(0); // an odd final would leave a team without an opponent every round
+        expect(plan.qualifiersPerGroup).toBeLessThanOrEqual(plan.groupSize);
+        expect(plan.groupRoundSpacingMinutes).toBeGreaterThanOrEqual(MIN_ROUND_SPACING_MINUTES);
+        // Rounds start on the hour or the half hour, never at 19:12.
+        expect(plan.groupRoundSpacingMinutes % 30).toBe(0);
+    });
+    it('fits the whole round robin inside the group-stage window until it genuinely cannot', () => {
+        for (const n of [1, 40, 100, 250, 700]) {
+            const plan = planEventGroups(n, WEEK);
+            expect(plan.overflows).toBe(false);
+            expect((plan.groupSize - 1) * plan.groupRoundSpacingMinutes).toBeLessThanOrEqual(WEEK * 60);
+        }
+        // 12 groups of 168 needs 167 rounds; at the one-hour minimum that is far more than six days, so the plan
+        // reports the overflow instead of silently generating a schedule that runs past the deadline.
+        expect(planEventGroups(2000, WEEK).overflows).toBe(true);
+    });
+    it('paces rounds to the window it is given, so a shorter event packs them tighter', () => {
+        const long = planEventGroups(40, WEEK);
+        const short = planEventGroups(40, groupStageHours({ ...COMMONS, durationDays: 3 })); // 48h
+        expect(short.groupSize).toBe(long.groupSize);
+        expect(short.groupRoundSpacingMinutes).toBeLessThan(long.groupRoundSpacingMinutes);
+        expect((short.groupSize - 1) * short.groupRoundSpacingMinutes).toBeLessThanOrEqual(48 * 60);
+    });
+});

package/dist/esm/src/service/competition/index.d.ts

@@ -1,5 +1,8 @@
 export * from './standing';
 export * from './season';
+export * from './event-schedule';
+export * from './event-draft';
+export * from './event-rewards';
 export * from './league';
 export * from './division';
 export * from './iteration';

package/dist/esm/src/service/competition/index.js

@@ -1,5 +1,8 @@
 export * from './standing';
 export * from './season';
+export * from './event-schedule';
+export * from './event-draft';
+export * from './event-rewards';
 export * from './league';
 export * from './division';
 export * from './iteration';

package/dist/esm/src/service/match/index.d.ts

@@ -4,6 +4,7 @@ export * from './match-generator';
 export * from './match-rating';
 export * from './match-set';
 export * from './rally';
+export * from './round-robin';
 export * from './point-breakdown';
 export * from './rally-metrics';
 export * from './court-position';

package/dist/esm/src/service/match/index.js

@@ -4,6 +4,7 @@ export * from './match-generator';
 export * from './match-rating';
 export * from './match-set';
 export * from './rally';
+export * from './round-robin';
 export * from './point-breakdown';
 export * from './rally-metrics';
 export * from './court-position';

package/dist/esm/src/service/match/match-generator.js

@@ -2,9 +2,13 @@ import dayjs from 'dayjs';
 import utc from 'dayjs/plugin/utc';
 import { v4 as uuidv4 } from 'uuid';
 import { Match } from './match';
+import { roundRobinRounds } from './round-robin';
 import { shuffle } from '../utils';
 import { StatusEnum } from '../../data';
 dayjs.extend(utc);
+// Consecutive matches in a league season start half an hour apart, so a 16-team double round robin (240 matches)
+// spans five days from the iteration's Monday.
+const MATCH_SPACING_MINUTES = 30;
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class
 export default class MatchGenerator {
     static generateMatches(teams, baseDate) {
@@ -16,57 +20,30 @@ export default class MatchGenerator {
         if (t.size !== teams.length) {
             throw new Error('DUPLICATE_TEAMS');
         }
-        let shuffled = shuffle([...teams]);
-        const l = shuffled.length - 1;
-        const half = Math.ceil(shuffled.length / 2);
-        const matches = [];
-        // We fix the first team
-        let firstTeam = shuffled.shift();
-        if (firstTeam == null) {
+        if (teams.length < 1) {
             throw new Error('EMPTY_TEAM_ARRAY');
         }
-        let homeRow;
-        let awayRow;
-        for (let i = 0; i < l; i++) {
-            // split array in 2 halves
-            const row1 = shuffled.slice(0, half);
-            const row2 = shuffled.slice(half);
-            row2.push(firstTeam);
-            if (i % 2 === 0) {
-                homeRow = row1;
-                awayRow = row2;
-            }
-            else {
-                homeRow = row2;
-                awayRow = row1;
-            }
-            for (let j = 0; j < half; j++) {
-                matches.push(Match.create({
-                    id: uuidv4(),
-                    homeTeam: homeRow[j],
-                    awayTeam: awayRow[j],
-                    scheduledDate: date.toDate(),
-                    status: StatusEnum.PENDING
-                }));
-                date = date.add(30, 'minutes');
-            }
-            firstTeam = row2.pop();
-            row1.unshift(row2.shift());
-            row2.push(row1.pop());
-            shuffled = [...row1, ...row2];
-        }
-        // Generate Inverted matches for home-away pairings
-        matches.push(...matches.map(match => {
+        const nextDate = () => {
             const scheduledDate = date.toDate();
-            date = date.add(30, 'minutes');
-            return Match.create({
-                id: uuidv4(),
-                homeTeam: match.awayTeam,
-                awayTeam: match.homeTeam,
-                scheduledDate,
-                status: StatusEnum.PENDING
-            });
+            date = date.add(MATCH_SPACING_MINUTES, 'minutes');
+            return scheduledDate;
+        };
+        // First leg: one pass of the round robin, matches laid out back to back in round order.
+        const firstLeg = roundRobinRounds(shuffle([...teams])).flat().map(([homeTeam, awayTeam]) => Match.create({
+            id: uuidv4(),
+            homeTeam,
+            awayTeam,
+            scheduledDate: nextDate(),
+            status: StatusEnum.PENDING
+        }));
+        // Second leg: the same fixtures with the sides swapped, so every pairing is played home and away.
+        const secondLeg = firstLeg.map(match => Match.create({
+            id: uuidv4(),
+            homeTeam: match.awayTeam,
+            awayTeam: match.homeTeam,
+            scheduledDate: nextDate(),
+            status: StatusEnum.PENDING
         }));
-        return matches;
+        return [...firstLeg, ...secondLeg];
     }
 }

package/dist/esm/src/service/match/match-generator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/service/match/match-generator.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from '@jest/globals';
+import MatchGenerator from './match-generator';
+import { makeTeam } from '../test-helpers';
+// The league season schedule. These assertions pin the behaviour the rollover depends on, so the shared
+// roundRobinRounds helper (used by events too) cannot silently change how a season is laid out.
+const MONDAY = new Date('2026-07-20T00:00:00.000Z');
+function orderedKey(match) {
+    return `${match.homeTeam.id}>${match.awayTeam.id}`;
+}
+describe('MatchGenerator.generateMatches()', () => {
+    it('plays a full double round robin for a 16-team division', () => {
+        const teams = Array.from({ length: 16 }, () => makeTeam());
+        const matches = MatchGenerator.generateMatches(teams, MONDAY);
+        // 16 teams x 15 opponents, home and away.
+        expect(matches).toHaveLength(240);
+        const seen = new Set(matches.map(orderedKey));
+        expect(seen.size).toBe(240);
+        // Every ordered pairing exists exactly once, so every team hosts and visits every other team.
+        for (const home of teams) {
+            for (const away of teams) {
+                if (home.id === away.id)
+                    continue;
+                expect(seen.has(`${home.id}>${away.id}`)).toBe(true);
+            }
+        }
+    });
+    it('anchors to 00:00 UTC of the base day and spaces matches 30 minutes apart', () => {
+        const teams = Array.from({ length: 16 }, () => makeTeam());
+        const matches = MatchGenerator.generateMatches(teams, new Date('2026-07-20T17:42:11.000Z'));
+        const times = matches.map(m => m.scheduledDate.getTime()).sort((a, b) => a - b);
+        expect(new Date(times[0]).toISOString()).toBe('2026-07-20T00:00:00.000Z');
+        for (let i = 1; i < times.length; i++) {
+            expect(times[i] - times[i - 1]).toBe(30 * 60 * 1000);
+        }
+        // 240 matches at half-hour spacing = five days, ending Friday 23:30 UTC.
+        expect(new Date(times[times.length - 1]).toISOString()).toBe('2026-07-24T23:30:00.000Z');
+    });
+    it('rejects a duplicated team and an empty division', () => {
+        const team = makeTeam();
+        expect(() => MatchGenerator.generateMatches([team, team], MONDAY)).toThrow('DUPLICATE_TEAMS');
+        expect(() => MatchGenerator.generateMatches([], MONDAY)).toThrow('EMPTY_TEAM_ARRAY');
+    });
+});

package/dist/esm/src/service/match/round-robin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Circle-method single round robin. Returns one entry per round, each holding the pairings that round plays,
+ * as `[home, away]` tuples. Every unordered pair of entrants appears exactly once across all rounds.
+ *
+ * An ODD entrant count produces a bye: one entrant sits out each round, so a round has `floor(n / 2)` pairings
+ * instead of `n / 2`. Callers that need everyone playing every round must pad to an even count first.
+ *
+ * Home and away alternate by round and by court index, so no entrant ends up at home in all of its games. For a
+ * double round robin the caller replays the same rounds with the sides swapped, which balances them exactly.
+ */
+export declare function roundRobinRounds<T>(entrants: T[]): Array<Array<[T, T]>>;