volleyballsimtypes 0.0.489 → 0.0.492

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

@@ -0,0 +1,89 @@
+import { describe, it, expect } from '@jest/globals';
+import { DRAFT_PLAN, DRAFT_SQUAD_SIZE, PACK_SIZE, draftPackRole, generatePack, isDraftComplete, packQualityBand } from './event-draft';
+import { RarityEnum, RoleEnum, calculateRoleScore } from '../player';
+import { makeCountry } from '../test-helpers';
+const COUNTRY = makeCountry();
+describe('DRAFT_PLAN', () => {
+    it('drafts a full 14-player squad, one pick per pack', () => {
+        expect(DRAFT_SQUAD_SIZE).toBe(14);
+        expect(DRAFT_PLAN).toHaveLength(14);
+    });
+    it('guarantees a positionally valid squad', () => {
+        const counts = DRAFT_PLAN.reduce((acc, role) => {
+            acc[role] = (acc[role] ?? 0) + 1;
+            return acc;
+        }, {});
+        expect(counts[RoleEnum.SETTER]).toBe(2);
+        expect(counts[RoleEnum.OUTSIDE_HITTER]).toBe(4);
+        expect(counts[RoleEnum.MIDDLE_BLOCKER]).toBe(3);
+        expect(counts[RoleEnum.OPPOSITE_HITTER]).toBe(2);
+        expect(counts[RoleEnum.LIBERO]).toBe(2);
+        expect(counts.ANY).toBe(1);
+        // Enough for a legal starting six plus a libero, whatever the free pack is spent on: a 5-1 needs a setter,
+        // two middles, two outsides and an opposite on court, and a libero off it.
+        expect(counts[RoleEnum.SETTER]).toBeGreaterThanOrEqual(1);
+        expect(counts[RoleEnum.MIDDLE_BLOCKER]).toBeGreaterThanOrEqual(2);
+        expect(counts[RoleEnum.OUTSIDE_HITTER]).toBeGreaterThanOrEqual(2);
+        expect(counts[RoleEnum.OPPOSITE_HITTER]).toBeGreaterThanOrEqual(1);
+        expect(counts[RoleEnum.LIBERO]).toBeGreaterThanOrEqual(1);
+    });
+    it('walks pack by pack and then reports the draft complete', () => {
+        for (let i = 0; i < DRAFT_SQUAD_SIZE; i++) {
+            expect(draftPackRole(i)).toBeDefined();
+            expect(isDraftComplete(i)).toBe(false);
+        }
+        expect(draftPackRole(DRAFT_SQUAD_SIZE)).toBeUndefined();
+        expect(isDraftComplete(DRAFT_SQUAD_SIZE)).toBe(true);
+    });
+});
+describe('generatePack()', () => {
+    const first = (roles) => roles[0];
+    it.each([RarityEnum.COMMON, RarityEnum.RARE, RarityEnum.LEGENDARY])('offers %s players of the pack role, all inside the fairness band', (rarity) => {
+        const role = RoleEnum.OUTSIDE_HITTER;
+        const band = packQualityBand(COUNTRY, rarity, role);
+        const pack = generatePack(COUNTRY, rarity, role, () => band, first);
+        expect(pack).toHaveLength(PACK_SIZE);
+        for (const player of pack) {
+            expect(player.rarity).toBe(rarity);
+            expect(player.roles).toContain(role);
+            const score = calculateRoleScore(player.stats, role);
+            expect(score).toBeGreaterThanOrEqual(band.min);
+            expect(score).toBeLessThanOrEqual(band.max);
+        }
+    });
+    it('keeps two packs of the same role comparable', () => {
+        const role = RoleEnum.MIDDLE_BLOCKER;
+        const band = packQualityBand(COUNTRY, RarityEnum.RARE, role);
+        const score = (p) => calculateRoleScore(p.stats, role);
+        const a = generatePack(COUNTRY, RarityEnum.RARE, role, () => band, first).map(score);
+        const b = generatePack(COUNTRY, RarityEnum.RARE, role, () => band, first).map(score);
+        // The point of the band: the best pack cannot run away from the worst one.
+        const spread = Math.max(...a, ...b) - Math.min(...a, ...b);
+        expect(spread).toBeLessThanOrEqual(band.max - band.min);
+    });
+    it('rolls a free pack at the role it is handed', () => {
+        const band = packQualityBand(COUNTRY, RarityEnum.COMMON, RoleEnum.LIBERO);
+        const pack = generatePack(COUNTRY, RarityEnum.COMMON, 'ANY', () => band, () => RoleEnum.LIBERO);
+        expect(pack).toHaveLength(PACK_SIZE);
+        for (const player of pack)
+            expect(player.roles).toContain(RoleEnum.LIBERO);
+    });
+    it('terminates even when nothing can land in band', () => {
+        const impossible = { role: RoleEnum.SETTER, min: Number.MAX_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER };
+        const pack = generatePack(COUNTRY, RarityEnum.COMMON, RoleEnum.SETTER, () => impossible, first);
+        // Generation gives up rather than spinning: a full pack is still returned.
+        expect(pack).toHaveLength(PACK_SIZE);
+    });
+});
+describe('packQualityBand()', () => {
+    it('brackets the median of what the generator actually produces', () => {
+        const band = packQualityBand(COUNTRY, RarityEnum.LEGENDARY, RoleEnum.SETTER);
+        expect(band.min).toBeLessThan(band.max);
+        expect(band.min).toBeGreaterThan(0);
+    });
+    it('scales with rarity, so a legendary band sits above a common one', () => {
+        const common = packQualityBand(COUNTRY, RarityEnum.COMMON, RoleEnum.OUTSIDE_HITTER);
+        const legendary = packQualityBand(COUNTRY, RarityEnum.LEGENDARY, RoleEnum.OUTSIDE_HITTER);
+        expect(legendary.min).toBeGreaterThan(common.max);
+    });
+});

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

@@ -0,0 +1,26 @@
+export type EventRewardBand = 'PARTICIPATION' | 'TOP_20' | 'TOP_10' | 'TOP_5' | 'TOP_3' | 'TOP_1';
+export interface EventRewardRow {
+    readonly band: EventRewardBand;
+    /** Best final position that earns this row; PARTICIPATION has none. */
+    readonly maxPosition: number | null;
+    /** Event Packs awarded by this row alone. */
+    readonly packs: number;
+    /** Coins awarded by this row alone. */
+    readonly coins: number;
+}
+/**
+ * Best band first. A team earns its own row and every row BELOW it, which is what "cumulative" means: first
+ * place collects all six.
+ */
+export declare const EVENT_REWARDS: readonly EventRewardRow[];
+/**
+ * The band a finish falls into. `position` is the place in the FINAL table; null means the team never reached
+ * the final, and so does any position past the last banded row, which both count as taking part.
+ */
+export declare function eventRewardBandFor(position: number | null): EventRewardBand;
+export interface EventPayout {
+    readonly packs: number;
+    readonly coins: number;
+}
+/** Everything a finish earns, adding its own row to every row beneath it. */
+export declare function eventPayoutFor(position: number | null): EventPayout;

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

@@ -0,0 +1,44 @@
+// What an event pays out, and the band a team's finish falls into. Owner-defined 2026-07-23.
+//
+// One source of truth for three consumers: the simulator grants from it, the About view lists it, and the
+// accolades page names the band. Rewards are CUMULATIVE, so a team collects every row from Participation down
+// to its own placement.
+/**
+ * Best band first. A team earns its own row and every row BELOW it, which is what "cumulative" means: first
+ * place collects all six.
+ */
+export const EVENT_REWARDS = [
+    { band: 'TOP_1', maxPosition: 1, packs: 1, coins: 0 },
+    { band: 'TOP_3', maxPosition: 3, packs: 0, coins: 500 },
+    { band: 'TOP_5', maxPosition: 5, packs: 0, coins: 1000 },
+    { band: 'TOP_10', maxPosition: 10, packs: 1, coins: 0 },
+    { band: 'TOP_20', maxPosition: 20, packs: 0, coins: 1000 },
+    { band: 'PARTICIPATION', maxPosition: null, packs: 1, coins: 1000 }
+];
+/**
+ * The band a finish falls into. `position` is the place in the FINAL table; null means the team never reached
+ * the final, and so does any position past the last banded row, which both count as taking part.
+ */
+export function eventRewardBandFor(position) {
+    if (position == null)
+        return 'PARTICIPATION';
+    // Rows are ordered best-first, so the FIRST row the position satisfies is the narrowest band it earns.
+    // Scanning to the end instead would always land on the widest, handing first place a "top 20" badge.
+    for (const row of EVENT_REWARDS) {
+        if (row.maxPosition != null && position <= row.maxPosition)
+            return row.band;
+    }
+    return 'PARTICIPATION';
+}
+/** Everything a finish earns, adding its own row to every row beneath it. */
+export function eventPayoutFor(position) {
+    const band = eventRewardBandFor(position);
+    const from = EVENT_REWARDS.findIndex(row => row.band === band);
+    let packs = 0;
+    let coins = 0;
+    for (const row of EVENT_REWARDS.slice(from)) {
+        packs += row.packs;
+        coins += row.coins;
+    }
+    return { packs, coins };
+}

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

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

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';