volleyballsimtypes 0.0.491 → 0.0.493

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

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const event_draft_1 = require("./event-draft");
+const player_1 = require("../player");
+const test_helpers_1 = require("../test-helpers");
+const COUNTRY = (0, test_helpers_1.makeCountry)();
+const first = (roles) => roles[0];
+// Aggregate helpers: skew is statistical, so the behaviour tests use large samples and generous margins to stay
+// off the flaky edge while still failing loudly if the skew were removed.
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.floor(sorted.length / 2)];
+}
+function percentile(values, p) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.floor((sorted.length - 1) * p)];
+}
+/** Role scores of `n` recruits drawn the way the DRAFT does (generatePack applies EVENT_DRAFT_TOP_SKEW). */
+function draftScores(rarity, role, n) {
+    const out = [];
+    while (out.length < n) {
+        for (const p of (0, event_draft_1.generatePack)(COUNTRY, rarity, role, first))
+            out.push((0, player_1.calculateRoleScore)(p.stats, role));
+    }
+    return out.slice(0, n);
+}
+/** Role scores of `n` recruits drawn UNIFORMLY (the generator's historic behaviour, skew 0). */
+function uniformScores(rarity, role, n) {
+    return Array.from({ length: n }, () => (0, player_1.calculateRoleScore)(player_1.PlayerGenerator.generatePlayer(COUNTRY, rarity, role, false, 1, 0).stats, role));
+}
+(0, globals_1.describe)('DRAFT_PLAN', () => {
+    (0, globals_1.it)('drafts a full 14-player squad, one pick per pack', () => {
+        (0, globals_1.expect)(event_draft_1.DRAFT_SQUAD_SIZE).toBe(14);
+        (0, globals_1.expect)(event_draft_1.DRAFT_PLAN).toHaveLength(14);
+    });
+    (0, globals_1.it)('guarantees a positionally valid squad', () => {
+        const counts = event_draft_1.DRAFT_PLAN.reduce((acc, role) => {
+            acc[role] = (acc[role] ?? 0) + 1;
+            return acc;
+        }, {});
+        (0, globals_1.expect)(counts[player_1.RoleEnum.SETTER]).toBe(2);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.OUTSIDE_HITTER]).toBe(4);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.MIDDLE_BLOCKER]).toBe(3);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.OPPOSITE_HITTER]).toBe(2);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.LIBERO]).toBe(2);
+        (0, globals_1.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.
+        (0, globals_1.expect)(counts[player_1.RoleEnum.SETTER]).toBeGreaterThanOrEqual(1);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.MIDDLE_BLOCKER]).toBeGreaterThanOrEqual(2);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.OUTSIDE_HITTER]).toBeGreaterThanOrEqual(2);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.OPPOSITE_HITTER]).toBeGreaterThanOrEqual(1);
+        (0, globals_1.expect)(counts[player_1.RoleEnum.LIBERO]).toBeGreaterThanOrEqual(1);
+    });
+    (0, globals_1.it)('walks pack by pack and then reports the draft complete', () => {
+        for (let i = 0; i < event_draft_1.DRAFT_SQUAD_SIZE; i++) {
+            (0, globals_1.expect)((0, event_draft_1.draftPackRole)(i)).toBeDefined();
+            (0, globals_1.expect)((0, event_draft_1.isDraftComplete)(i)).toBe(false);
+        }
+        (0, globals_1.expect)((0, event_draft_1.draftPackRole)(event_draft_1.DRAFT_SQUAD_SIZE)).toBeUndefined();
+        (0, globals_1.expect)((0, event_draft_1.isDraftComplete)(event_draft_1.DRAFT_SQUAD_SIZE)).toBe(true);
+    });
+});
+(0, globals_1.describe)('generatePack()', () => {
+    globals_1.it.each([player_1.RarityEnum.COMMON, player_1.RarityEnum.RARE, player_1.RarityEnum.LEGENDARY])('offers %s players of the pack role', (rarity) => {
+        const role = player_1.RoleEnum.OUTSIDE_HITTER;
+        const pack = (0, event_draft_1.generatePack)(COUNTRY, rarity, role, first);
+        (0, globals_1.expect)(pack).toHaveLength(event_draft_1.PACK_SIZE);
+        for (const player of pack) {
+            (0, globals_1.expect)(player.rarity).toBe(rarity);
+            (0, globals_1.expect)(player.roles).toContain(role);
+        }
+    });
+    (0, globals_1.it)('rolls a free (ANY) pack at the role it is handed', () => {
+        const pack = (0, event_draft_1.generatePack)(COUNTRY, player_1.RarityEnum.COMMON, 'ANY', () => player_1.RoleEnum.LIBERO);
+        (0, globals_1.expect)(pack).toHaveLength(event_draft_1.PACK_SIZE);
+        for (const player of pack)
+            (0, globals_1.expect)(player.roles).toContain(player_1.RoleEnum.LIBERO);
+    });
+});
+(0, globals_1.describe)('EVENT_DRAFT_TOP_SKEW', () => {
+    (0, globals_1.it)('skews commons and rares toward the top and leaves legendaries (and up) uniform', () => {
+        (0, globals_1.expect)(event_draft_1.EVENT_DRAFT_TOP_SKEW[player_1.RarityEnum.COMMON]).toBeGreaterThan(0);
+        (0, globals_1.expect)(event_draft_1.EVENT_DRAFT_TOP_SKEW[player_1.RarityEnum.RARE]).toBeGreaterThan(0);
+        (0, globals_1.expect)(event_draft_1.EVENT_DRAFT_TOP_SKEW[player_1.RarityEnum.LEGENDARY]).toBe(0);
+        (0, globals_1.expect)(event_draft_1.EVENT_DRAFT_TOP_SKEW[player_1.RarityEnum.MYTHIC]).toBe(0);
+        (0, globals_1.expect)(event_draft_1.EVENT_DRAFT_TOP_SKEW[player_1.RarityEnum.SPECIAL]).toBe(0);
+    });
+});
+(0, globals_1.describe)('draft skew behaviour', () => {
+    const N = 2500;
+    const role = player_1.RoleEnum.OUTSIDE_HITTER;
+    globals_1.it.each([player_1.RarityEnum.COMMON, player_1.RarityEnum.RARE])('draws %s recruits near the top: the typical recruit outscores a uniform draw, and most land in its top fifth', (rarity) => {
+        const uniform = uniformScores(rarity, role, N);
+        const drafted = draftScores(rarity, role, N);
+        // The 80th percentile of a UNIFORM draw is the entry to the top fifth of the range.
+        const topFifthFloor = percentile(uniform, 0.80);
+        const draftedInTopFifth = drafted.filter(s => s >= topFifthFloor).length / drafted.length;
+        // A uniform draw puts ~20% here; the skew must push well past that (measured ~65-88% at skew 2).
+        (0, globals_1.expect)(draftedInTopFifth).toBeGreaterThan(0.45);
+        // The typical drafted recruit clearly outscores the typical uniform one.
+        (0, globals_1.expect)(median(drafted)).toBeGreaterThan(median(uniform));
+        // But it is a skew, not a clamp to the maximum: recruits still spread out, and the typical one sits
+        // below the best in the sample rather than everyone landing on the ceiling.
+        (0, globals_1.expect)(percentile(drafted, 0.10)).toBeLessThan(percentile(drafted, 0.90));
+        (0, globals_1.expect)(median(drafted)).toBeLessThan(Math.max(...drafted));
+    });
+    (0, globals_1.it)('leaves legendary recruits uniform: no top-end lift over a plain draw', () => {
+        const uniform = uniformScores(player_1.RarityEnum.LEGENDARY, role, N);
+        const drafted = draftScores(player_1.RarityEnum.LEGENDARY, role, N);
+        const topFifthFloor = percentile(uniform, 0.80);
+        const draftedInTopFifth = drafted.filter(s => s >= topFifthFloor).length / drafted.length;
+        // Same distribution as uniform (skew 0), so it stays near the ~20% a plain draw produces, nowhere near the
+        // >45% the skewed lower rarities reach.
+        (0, globals_1.expect)(draftedInTopFifth).toBeLessThan(0.35);
+    });
+});

package/dist/cjs/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/cjs/src/service/competition/event-rewards.js

@@ -0,0 +1,49 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_REWARDS = void 0;
+exports.eventRewardBandFor = eventRewardBandFor;
+exports.eventPayoutFor = eventPayoutFor;
+/**
+ * Best band first. A team earns its own row and every row BELOW it, which is what "cumulative" means: first
+ * place collects all six.
+ */
+exports.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.
+ */
+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 exports.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. */
+function eventPayoutFor(position) {
+    const band = eventRewardBandFor(position);
+    const from = exports.EVENT_REWARDS.findIndex(row => row.band === band);
+    let packs = 0;
+    let coins = 0;
+    for (const row of exports.EVENT_REWARDS.slice(from)) {
+        packs += row.packs;
+        coins += row.coins;
+    }
+    return { packs, coins };
+}

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

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

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const event_rewards_1 = require("./event-rewards");
+(0, globals_1.describe)('eventRewardBandFor()', () => {
+    globals_1.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) => {
+        (0, globals_1.expect)((0, event_rewards_1.eventRewardBandFor)(position)).toBe(band);
+    });
+    (0, globals_1.it)('treats a team that never reached the final as participation', () => {
+        (0, globals_1.expect)((0, event_rewards_1.eventRewardBandFor)(null)).toBe('PARTICIPATION');
+    });
+});
+(0, globals_1.describe)('eventPayoutFor()', () => {
+    globals_1.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) => {
+        (0, globals_1.expect)((0, event_rewards_1.eventPayoutFor)(position)).toEqual({ packs, coins });
+    });
+    (0, globals_1.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 = (0, event_rewards_1.eventPayoutFor)(finishes[i - 1]);
+            const better = (0, event_rewards_1.eventPayoutFor)(finishes[i]);
+            (0, globals_1.expect)(better.packs).toBeGreaterThanOrEqual(worse.packs);
+            (0, globals_1.expect)(better.coins).toBeGreaterThanOrEqual(worse.coins);
+        }
+    });
+    (0, globals_1.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_1.EVENT_REWARDS.reduce((acc, row) => ({ packs: acc.packs + row.packs, coins: acc.coins + row.coins }), { packs: 0, coins: 0 });
+        (0, globals_1.expect)((0, event_rewards_1.eventPayoutFor)(1)).toEqual(total);
+        (0, globals_1.expect)(total).toEqual({ packs: 3, coins: 3500 });
+    });
+});

package/dist/cjs/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/cjs/src/service/competition/event-schedule.js

@@ -0,0 +1,141 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUND_SPACING_GRID_MINUTES = exports.EVENT_GROUP_TIERS = exports.FINAL_ROUND_SPACING_MINUTES = exports.MIN_ROUND_SPACING_MINUTES = exports.MIN_GROUP_SIZE = exports.MAX_FINAL_SIZE = exports.REVIEW_DAYS = exports.MAX_REGISTRATION_DAYS = exports.MIN_REGISTRATION_DAYS = exports.MIN_DURATION_DAYS = exports.EVENT_CATALOGUE = void 0;
+exports.eventGroupTierFor = eventGroupTierFor;
+exports.eventDefinitionForKey = eventDefinitionForKey;
+exports.eventWindowsFor = eventWindowsFor;
+exports.groupStageHours = groupStageHours;
+exports.eventStatusAt = eventStatusAt;
+exports.planEventGroups = planEventGroups;
+const dayjs_1 = __importDefault(require("dayjs"));
+const utc_1 = __importDefault(require("dayjs/plugin/utc"));
+const player_1 = require("../player");
+dayjs_1.default.extend(utc_1.default);
+// 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.
+exports.EVENT_CATALOGUE = [
+    { key: 'WAR_OF_THE_COMMONS', format: 'GROUPS_FINAL', rarity: player_1.RarityEnum.COMMON, durationDays: 7 },
+    { key: 'RARE_GEMS', format: 'GROUPS_FINAL', rarity: player_1.RarityEnum.RARE, durationDays: 7 },
+    { key: 'STUFF_OF_LEGENDS', format: 'GROUPS_FINAL', rarity: player_1.RarityEnum.LEGENDARY, durationDays: 7 }
+];
+/** An event must be long enough to hold a group stage AND a final day. */
+exports.MIN_DURATION_DAYS = 2;
+/** Registration has to give players a real chance to build a squad, and cannot be scheduled absurdly far out. */
+exports.MIN_REGISTRATION_DAYS = 1;
+exports.MAX_REGISTRATION_DAYS = 30;
+/** Results stay readable for this long after an event ends, then everything but the Event row is deleted. */
+exports.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.
+ */
+exports.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. */
+exports.MIN_GROUP_SIZE = 16;
+/** Rounds are never closer together than an hour, which is what bounds how large a group can be. */
+exports.MIN_ROUND_SPACING_MINUTES = 60;
+/** One match per hour in the final: 24 teams = 23 rounds, 00:00 to 23:00. */
+exports.FINAL_ROUND_SPACING_MINUTES = 60;
+exports.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. */
+function eventGroupTierFor(participantCount) {
+    return exports.EVENT_GROUP_TIERS.find(tier => participantCount < tier.maxParticipants) ?? exports.EVENT_GROUP_TIERS[exports.EVENT_GROUP_TIERS.length - 1];
+}
+/** The preset a stored event was created from. Its rules are read from this, never re-derived. */
+function eventDefinitionForKey(key) {
+    const definition = exports.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
+ * ```
+ */
+function eventWindowsFor(definition, startsAt, registrationDays) {
+    const start = dayjs_1.default.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 + exports.REVIEW_DAYS, 'day').toDate()
+    };
+}
+/** How long the group stage has, in hours: everything before the final day. */
+function groupStageHours(definition) {
+    return (definition.durationDays - 1) * 24;
+}
+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.
+ */
+exports.ROUND_SPACING_GRID_MINUTES = 30;
+function snapToGrid(minutes) {
+    return Math.floor(minutes / exports.ROUND_SPACING_GRID_MINUTES) * exports.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.
+ */
+function planEventGroups(participantCount, stageHours) {
+    const tier = eventGroupTierFor(participantCount);
+    const groupCount = tier.groupCount;
+    const groupSize = Math.max(exports.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(exports.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 < exports.MIN_ROUND_SPACING_MINUTES
+    };
+}

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

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