diff --git a/apps/api/src/modules/competition/domain/series-graph.spec.ts b/apps/api/src/modules/competition/domain/series-graph.spec.ts index c989c739..c80cde07 100644 --- a/apps/api/src/modules/competition/domain/series-graph.spec.ts +++ b/apps/api/src/modules/competition/domain/series-graph.spec.ts @@ -1,5 +1,18 @@ import { generateSeriesGraph } from './series-graph'; +type GraphInput = Parameters[0]; +type ExplicitRoundRobinPairing = { + roundNumber: number; + matchNumber: number; + teamAId: string; + teamBId: string; +}; +type ExplicitRoundRobinGraphInput = Omit & { + format: Extract & { + pairings: readonly ExplicitRoundRobinPairing[]; + }; +}; + describe('generateSeriesGraph', () => { it('generates a deterministic graph with stable opaque ids', () => { const input = { @@ -112,8 +125,181 @@ describe('generateSeriesGraph', () => { expect(error).toMatchObject({ code: 'INVALID_FIRST_TO_RULE' }); } }); + + it('reproduces an explicit persisted round-robin schedule by TeamId and pairing position', () => { + const input: ExplicitRoundRobinGraphInput = { + competitionId: 'competition-persisted-round-robin', + teams: Array.from({ length: 8 }, (_, index) => ({ + teamId: `team-${index + 1}`, + displayOrder: 8 - index, + seedNumber: index + 1, + })), + format: { + type: 'round-robin', + rule: fixedGames(1), + maxRounds: 3, + tieBreakers: ['series-wins', 'game-diff', 'head-to-head'], + // Persisted schedules need not arrive in display order. Their explicit + // round/match positions, rather than array position, define identity. + pairings: [ + pairing(3, 4, 'team-6', 'team-7'), + pairing(1, 2, 'team-3', 'team-4'), + pairing(2, 1, 'team-1', 'team-3'), + pairing(1, 4, 'team-7', 'team-8'), + pairing(3, 1, 'team-1', 'team-4'), + pairing(2, 3, 'team-5', 'team-7'), + pairing(1, 1, 'team-1', 'team-2'), + pairing(3, 3, 'team-5', 'team-8'), + pairing(2, 4, 'team-6', 'team-8'), + pairing(1, 3, 'team-5', 'team-6'), + pairing(3, 2, 'team-2', 'team-3'), + pairing(2, 2, 'team-2', 'team-4'), + ], + }, + }; + + const first = generateSeriesGraph(input); + const second = generateSeriesGraph(input); + + expect(second).toEqual(first); + expect( + first.map((series) => ({ + code: series.code, + roundNumber: series.stage.roundNumber, + displayOrder: series.stage.displayOrder, + sources: series.slots.map((slot) => slot.source), + })), + ).toEqual([ + roundRobinSeries('RR_R1_M1', 1, 1, 'team-1', 'team-2'), + roundRobinSeries('RR_R1_M2', 1, 2, 'team-3', 'team-4'), + roundRobinSeries('RR_R1_M3', 1, 3, 'team-5', 'team-6'), + roundRobinSeries('RR_R1_M4', 1, 4, 'team-7', 'team-8'), + roundRobinSeries('RR_R2_M1', 2, 5, 'team-1', 'team-3'), + roundRobinSeries('RR_R2_M2', 2, 6, 'team-2', 'team-4'), + roundRobinSeries('RR_R2_M3', 2, 7, 'team-5', 'team-7'), + roundRobinSeries('RR_R2_M4', 2, 8, 'team-6', 'team-8'), + roundRobinSeries('RR_R3_M1', 3, 9, 'team-1', 'team-4'), + roundRobinSeries('RR_R3_M2', 3, 10, 'team-2', 'team-3'), + roundRobinSeries('RR_R3_M3', 3, 11, 'team-5', 'team-8'), + roundRobinSeries('RR_R3_M4', 3, 12, 'team-6', 'team-7'), + ]); + }); + + it.each([ + { + name: 'a TeamId that is absent from the Competition', + replacement: pairing(1, 1, 'team-1', 'team-9'), + }, + { + name: 'the same TeamId in both slots', + replacement: pairing(1, 1, 'team-1', 'team-1'), + }, + { + name: 'a non-positive round number', + replacement: pairing(0, 1, 'team-1', 'team-2'), + }, + { + name: 'a non-positive match number', + replacement: pairing(1, 0, 'team-1', 'team-2'), + }, + ])( + 'rejects an explicit round-robin pairing with $name', + ({ replacement }) => { + const input = explicitRoundRobinInput([ + replacement, + pairing(1, 2, 'team-3', 'team-4'), + ]); + + expect(() => generateSeriesGraph(input)).toThrow( + expect.objectContaining({ code: 'INVALID_ROUND_ROBIN_PAIRING' }), + ); + }, + ); + + it.each([ + { + name: 'round and match position', + pairings: [ + pairing(1, 1, 'team-1', 'team-2'), + pairing(1, 1, 'team-3', 'team-4'), + ], + code: 'DUPLICATE_ROUND_ROBIN_PAIRING_POSITION', + }, + { + name: 'opponents with reversed slots', + pairings: [ + pairing(1, 1, 'team-1', 'team-2'), + pairing(2, 1, 'team-2', 'team-1'), + ], + code: 'DUPLICATE_ROUND_ROBIN_OPPONENTS', + }, + ])('rejects a duplicate explicit $name', ({ pairings, code }) => { + expect(() => + generateSeriesGraph(explicitRoundRobinInput(pairings)), + ).toThrow(expect.objectContaining({ code })); + }); }); function firstTo(winsRequired: number, maxGames: number) { return { type: 'first-to' as const, winsRequired, maxGames }; } + +function fixedGames(gameCount: number) { + return { + type: 'fixed-games' as const, + gameCount, + drawPolicy: 'allow' as const, + }; +} + +function pairing( + roundNumber: number, + matchNumber: number, + teamAId: string, + teamBId: string, +): ExplicitRoundRobinPairing { + return { + roundNumber, + matchNumber, + teamAId, + teamBId, + }; +} + +function explicitRoundRobinInput( + pairings: readonly ExplicitRoundRobinPairing[], +): ExplicitRoundRobinGraphInput { + return { + competitionId: 'competition-explicit-round-robin-validation', + teams: Array.from({ length: 4 }, (_, index) => ({ + teamId: `team-${index + 1}`, + displayOrder: index + 1, + seedNumber: index + 1, + })), + format: { + type: 'round-robin', + rule: fixedGames(1), + maxRounds: 2, + tieBreakers: ['series-wins', 'game-diff', 'head-to-head'], + pairings, + }, + }; +} + +function roundRobinSeries( + code: string, + roundNumber: number, + displayOrder: number, + teamAId: string, + teamBId: string, +) { + return { + code, + roundNumber, + displayOrder, + sources: [ + { type: 'team', teamId: teamAId }, + { type: 'team', teamId: teamBId }, + ], + }; +} diff --git a/apps/api/src/modules/competition/domain/series-graph.ts b/apps/api/src/modules/competition/domain/series-graph.ts index 6214040a..1b72d012 100644 --- a/apps/api/src/modules/competition/domain/series-graph.ts +++ b/apps/api/src/modules/competition/domain/series-graph.ts @@ -68,6 +68,13 @@ export interface CompetitionGraphTeam { seedNumber?: number; } +export interface RoundRobinPairing { + roundNumber: number; + matchNumber: number; + teamAId: string; + teamBId: string; +} + export type CompetitionGraphFormat = | { type: 'paired-series'; @@ -77,6 +84,7 @@ export type CompetitionGraphFormat = type: 'round-robin'; rule: FixedGamesSeriesRule; maxRounds?: number; + pairings?: readonly RoundRobinPairing[]; tieBreakers: readonly ['series-wins', 'game-diff', 'head-to-head']; } | { @@ -116,7 +124,7 @@ type TemplateParticipantSource = } | { type: 'series-slot'; seriesCode: string; slot: SeriesSlot }; -interface RoundRobinPairing { +interface CanonicalRoundRobinPairing { roundNumber: number; teamAIndex: number; teamBIndex: number; @@ -143,12 +151,7 @@ export function generateSeriesGraph( ); break; case 'round-robin': - graph = generateRoundRobinGraph( - input.competitionId, - teams, - input.format.rule, - input.format.maxRounds, - ); + graph = generateRoundRobinGraph(input.competitionId, teams, input.format); break; case 'double-elimination': graph = generateDoubleEliminationGraph( @@ -200,10 +203,9 @@ function generatePairedSeriesGraph( function generateRoundRobinGraph( competitionId: string, teams: CompetitionGraphTeam[], - rule: FixedGamesSeriesRule, - maxRounds?: number, + format: Extract, ): SeriesDefinition[] { - assertFixedGamesRule(rule); + assertFixedGamesRule(format.rule); if (teams.length < 2) { throw graphError( 'INVALID_ROUND_ROBIN_TEAM_COUNT', @@ -211,13 +213,16 @@ function generateRoundRobinGraph( ); } - const pairings = roundRobinPairings(teams.length, maxRounds); - const matchNumberByRound = new Map(); + const pairings = format.pairings + ? validateExplicitRoundRobinPairings( + teams, + format.pairings, + format.maxRounds, + ) + : canonicalRoundRobinPairings(teams, format.maxRounds); return pairings.map((pairing, index) => { - const matchNumber = (matchNumberByRound.get(pairing.roundNumber) ?? 0) + 1; - matchNumberByRound.set(pairing.roundNumber, matchNumber); - const code = `RR_R${pairing.roundNumber}_M${matchNumber}`; + const code = `RR_R${pairing.roundNumber}_M${pairing.matchNumber}`; return createSeriesDefinition({ competitionId, code, @@ -225,14 +230,117 @@ function generateRoundRobinGraph( roundNumber: pairing.roundNumber, displayOrder: index + 1, sources: [ - { type: 'team', teamId: teams[pairing.teamAIndex].teamId }, - { type: 'team', teamId: teams[pairing.teamBIndex].teamId }, + { type: 'team', teamId: pairing.teamAId }, + { type: 'team', teamId: pairing.teamBId }, ], - rule, + rule: format.rule, }); }); } +function canonicalRoundRobinPairings( + teams: CompetitionGraphTeam[], + maxRounds?: number, +): RoundRobinPairing[] { + const matchNumberByRound = new Map(); + return roundRobinPairings(teams.length, maxRounds).map((pairing) => { + const matchNumber = (matchNumberByRound.get(pairing.roundNumber) ?? 0) + 1; + matchNumberByRound.set(pairing.roundNumber, matchNumber); + return { + roundNumber: pairing.roundNumber, + matchNumber, + teamAId: teams[pairing.teamAIndex].teamId, + teamBId: teams[pairing.teamBIndex].teamId, + }; + }); +} + +function validateExplicitRoundRobinPairings( + teams: CompetitionGraphTeam[], + pairings: readonly RoundRobinPairing[], + maxRounds?: number, +): RoundRobinPairing[] { + if (pairings.length === 0) { + throw graphError( + 'INVALID_ROUND_ROBIN_PAIRING', + 'Explicit round-robin pairings cannot be empty.', + ); + } + const teamIds = new Set(teams.map(({ teamId }) => teamId)); + const positions = new Set(); + const opponentPairs = new Set(); + const teamsByRound = new Map>(); + const sorted = pairings + .map((pairing) => ({ ...pairing })) + .sort( + (left, right) => + left.roundNumber - right.roundNumber || + left.matchNumber - right.matchNumber, + ); + + for (const pairing of sorted) { + if ( + !Number.isInteger(pairing.roundNumber) || + pairing.roundNumber < 1 || + !Number.isInteger(pairing.matchNumber) || + pairing.matchNumber < 1 || + (maxRounds !== undefined && pairing.roundNumber > maxRounds) || + !teamIds.has(pairing.teamAId) || + !teamIds.has(pairing.teamBId) || + pairing.teamAId === pairing.teamBId + ) { + throw graphError( + 'INVALID_ROUND_ROBIN_PAIRING', + 'Every explicit round-robin pairing needs a valid position and two known, distinct teams.', + ); + } + + const position = `${pairing.roundNumber}:${pairing.matchNumber}`; + if (positions.has(position)) { + throw graphError( + 'DUPLICATE_ROUND_ROBIN_PAIRING_POSITION', + `Round-robin pairing position ${position} occurs more than once.`, + ); + } + positions.add(position); + + const opponents = [pairing.teamAId, pairing.teamBId].sort().join(':'); + if (opponentPairs.has(opponents)) { + throw graphError( + 'DUPLICATE_ROUND_ROBIN_OPPONENTS', + 'A round-robin opponent pair occurs more than once.', + ); + } + opponentPairs.add(opponents); + + const roundTeams = teamsByRound.get(pairing.roundNumber) ?? new Set(); + if (roundTeams.has(pairing.teamAId) || roundTeams.has(pairing.teamBId)) { + throw graphError( + 'INVALID_ROUND_ROBIN_PAIRING', + 'A team cannot appear in multiple Series in the same round.', + ); + } + roundTeams.add(pairing.teamAId); + roundTeams.add(pairing.teamBId); + teamsByRound.set(pairing.roundNumber, roundTeams); + } + + for (const roundNumber of new Set( + sorted.map((pairing) => pairing.roundNumber), + )) { + const matches = sorted.filter( + (pairing) => pairing.roundNumber === roundNumber, + ); + if (matches.some((pairing, index) => pairing.matchNumber !== index + 1)) { + throw graphError( + 'INVALID_ROUND_ROBIN_PAIRING', + `Round ${roundNumber} match numbers must be contiguous from one.`, + ); + } + } + return sorted; +} + function generateDoubleEliminationGraph( competitionId: string, teams: CompetitionGraphTeam[], @@ -436,7 +544,7 @@ function ruleForStage( function roundRobinPairings( teamCount: number, maxRounds?: number, -): RoundRobinPairing[] { +): CanonicalRoundRobinPairing[] { const bye = -1; const rotating = Array.from({ length: teamCount }, (_, index) => index); if (rotating.length % 2 === 1) rotating.push(bye); @@ -449,7 +557,7 @@ function roundRobinPairings( ? Math.floor(maxRounds) : fullRoundCount; const roundCount = Math.max(0, Math.min(fullRoundCount, requestedRounds)); - const pairings: RoundRobinPairing[] = []; + const pairings: CanonicalRoundRobinPairing[] = []; for (let roundIndex = 0; roundIndex < roundCount; roundIndex += 1) { for (let index = 0; index < rotating.length / 2; index += 1) { diff --git a/docs/specs/competition-result-domain.md b/docs/specs/competition-result-domain.md index ea00bcf0..e8f725fe 100644 --- a/docs/specs/competition-result-domain.md +++ b/docs/specs/competition-result-domain.md @@ -274,7 +274,7 @@ Migration builds new collections without dual canonical writes. `null`, mapping it to `pair`; an explicitly stored unknown mode remains quarantined instead of being guessed. - A persisted legacy round-robin `gameSchedule` is authoritative. Migration - normalizes it into explicit seed-based pairings on the Competition format so the + normalizes it into explicit TeamId-based pairings on the Competition format so the immutable Series graph reproduces the historical opponents and rounds instead of generating a different canonical schedule. Matches without a persisted schedule continue to use deterministic canonical round-robin generation. diff --git a/packages/contracts/src/format.ts b/packages/contracts/src/format.ts index 3fe13854..dde5b565 100644 --- a/packages/contracts/src/format.ts +++ b/packages/contracts/src/format.ts @@ -1,8 +1,5 @@ import type { TeamId } from "./ids.js"; -import type { - FirstToSeriesRule, - FixedGamesSeriesRule, -} from "./series.js"; +import type { FirstToSeriesRule, FixedGamesSeriesRule } from "./series.js"; export type CompetitionFormatType = | "paired-series" @@ -14,20 +11,21 @@ export interface PairedSeriesCompetitionFormat { rule: FixedGamesSeriesRule; } -export type RoundRobinTieBreaker = - | "series-wins" - | "game-diff" - | "head-to-head"; +export type RoundRobinTieBreaker = "series-wins" | "game-diff" | "head-to-head"; + +export interface RoundRobinPairing { + roundNumber: number; + matchNumber: number; + teamAId: TeamId; + teamBId: TeamId; +} export interface RoundRobinCompetitionFormat { type: "round-robin"; rule: FixedGamesSeriesRule; maxRounds?: number; - tieBreakers: [ - "series-wins", - "game-diff", - "head-to-head", - ]; + pairings?: RoundRobinPairing[]; + tieBreakers: ["series-wins", "game-diff", "head-to-head"]; } export interface DoubleEliminationSeriesRules { diff --git a/packages/contracts/test-d/contracts.test-d.ts b/packages/contracts/test-d/contracts.test-d.ts index 9cb613ee..c7cf755e 100644 --- a/packages/contracts/test-d/contracts.test-d.ts +++ b/packages/contracts/test-d/contracts.test-d.ts @@ -3,6 +3,7 @@ import type { CompetitionId, CompletedSeriesProjection, InProgressSeriesProjection, + RoundRobinCompetitionFormat, SeriesOutcome, TeamId, } from "../src/index.js"; @@ -26,3 +27,23 @@ export type InProgressSeriesCannotExposeOutcome = Expect< export type LegacyBracketModeIsNotACompetitionFormat = Expect< Not> >; + +type ExplicitRoundRobinPairing = NonNullable< + RoundRobinCompetitionFormat["pairings"] +>[number]; + +export type ExplicitRoundRobinPairingsAreOptional = Expect< + IsAssignable<{}, Pick> +>; + +export type ExplicitRoundRobinPairingsAreTeamIdBased = Expect< + IsAssignable< + ExplicitRoundRobinPairing, + { + roundNumber: number; + matchNumber: number; + teamAId: TeamId; + teamBId: TeamId; + } + > +>;