feat: preserve explicit round robin pairings

This commit is contained in:
dahyeon committed 2026-07-13 03:50:32 +00:00
1 parent 640e593676
commit c2f89f9cb2
5 files changed
+347 -34

No files matched your search

@@ -1,5 +1,18 @@
import { generateSeriesGraph } from './series-graph'; import { generateSeriesGraph } from './series-graph';
type GraphInput = Parameters<typeof generateSeriesGraph>[0];
type ExplicitRoundRobinPairing = {
roundNumber: number;
matchNumber: number;
teamAId: string;
teamBId: string;
};
type ExplicitRoundRobinGraphInput = Omit<GraphInput, 'format'> & {
format: Extract<GraphInput['format'], { type: 'round-robin' }> & {
pairings: readonly ExplicitRoundRobinPairing[];
};
};
describe('generateSeriesGraph', () => { describe('generateSeriesGraph', () => {
it('generates a deterministic graph with stable opaque ids', () => { it('generates a deterministic graph with stable opaque ids', () => {
const input = { const input = {
@@ -112,8 +125,181 @@ describe('generateSeriesGraph', () => {
expect(error).toMatchObject({ code: 'INVALID_FIRST_TO_RULE' }); 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) { function firstTo(winsRequired: number, maxGames: number) {
return { type: 'first-to' as const, winsRequired, maxGames }; 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 },
],
};
}
@@ -68,6 +68,13 @@ export interface CompetitionGraphTeam {
seedNumber?: number; seedNumber?: number;
} }
export interface RoundRobinPairing {
roundNumber: number;
matchNumber: number;
teamAId: string;
teamBId: string;
}
export type CompetitionGraphFormat = export type CompetitionGraphFormat =
| { | {
type: 'paired-series'; type: 'paired-series';
@@ -77,6 +84,7 @@ export type CompetitionGraphFormat =
type: 'round-robin'; type: 'round-robin';
rule: FixedGamesSeriesRule; rule: FixedGamesSeriesRule;
maxRounds?: number; maxRounds?: number;
pairings?: readonly RoundRobinPairing[];
tieBreakers: readonly ['series-wins', 'game-diff', 'head-to-head']; tieBreakers: readonly ['series-wins', 'game-diff', 'head-to-head'];
} }
| { | {
@@ -116,7 +124,7 @@ type TemplateParticipantSource =
} }
| { type: 'series-slot'; seriesCode: string; slot: SeriesSlot }; | { type: 'series-slot'; seriesCode: string; slot: SeriesSlot };
interface RoundRobinPairing { interface CanonicalRoundRobinPairing {
roundNumber: number; roundNumber: number;
teamAIndex: number; teamAIndex: number;
teamBIndex: number; teamBIndex: number;
@@ -143,12 +151,7 @@ export function generateSeriesGraph(
); );
break; break;
case 'round-robin': case 'round-robin':
graph = generateRoundRobinGraph( graph = generateRoundRobinGraph(input.competitionId, teams, input.format);
input.competitionId,
teams,
input.format.rule,
input.format.maxRounds,
);
break; break;
case 'double-elimination': case 'double-elimination':
graph = generateDoubleEliminationGraph( graph = generateDoubleEliminationGraph(
@@ -200,10 +203,9 @@ function generatePairedSeriesGraph(
function generateRoundRobinGraph( function generateRoundRobinGraph(
competitionId: string, competitionId: string,
teams: CompetitionGraphTeam[], teams: CompetitionGraphTeam[],
rule: FixedGamesSeriesRule, format: Extract<CompetitionGraphFormat, { type: 'round-robin' }>,
maxRounds?: number,
): SeriesDefinition[] { ): SeriesDefinition[] {
assertFixedGamesRule(rule); assertFixedGamesRule(format.rule);
if (teams.length < 2) { if (teams.length < 2) {
throw graphError( throw graphError(
'INVALID_ROUND_ROBIN_TEAM_COUNT', 'INVALID_ROUND_ROBIN_TEAM_COUNT',
@@ -211,13 +213,16 @@ function generateRoundRobinGraph(
); );
} }
const pairings = roundRobinPairings(teams.length, maxRounds); const pairings = format.pairings
const matchNumberByRound = new Map<number, number>(); ? validateExplicitRoundRobinPairings(
teams,
format.pairings,
format.maxRounds,
)
: canonicalRoundRobinPairings(teams, format.maxRounds);
return pairings.map((pairing, index) => { return pairings.map((pairing, index) => {
const matchNumber = (matchNumberByRound.get(pairing.roundNumber) ?? 0) + 1; const code = `RR_R${pairing.roundNumber}_M${pairing.matchNumber}`;
matchNumberByRound.set(pairing.roundNumber, matchNumber);
const code = `RR_R${pairing.roundNumber}_M${matchNumber}`;
return createSeriesDefinition({ return createSeriesDefinition({
competitionId, competitionId,
code, code,
@@ -225,14 +230,117 @@ function generateRoundRobinGraph(
roundNumber: pairing.roundNumber, roundNumber: pairing.roundNumber,
displayOrder: index + 1, displayOrder: index + 1,
sources: [ sources: [
{ type: 'team', teamId: teams[pairing.teamAIndex].teamId }, { type: 'team', teamId: pairing.teamAId },
{ type: 'team', teamId: teams[pairing.teamBIndex].teamId }, { type: 'team', teamId: pairing.teamBId },
], ],
rule, rule: format.rule,
}); });
}); });
} }
function canonicalRoundRobinPairings(
teams: CompetitionGraphTeam[],
maxRounds?: number,
): RoundRobinPairing[] {
const matchNumberByRound = new Map<number, number>();
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<string>();
const opponentPairs = new Set<string>();
const teamsByRound = new Map<number, Set<string>>();
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( function generateDoubleEliminationGraph(
competitionId: string, competitionId: string,
teams: CompetitionGraphTeam[], teams: CompetitionGraphTeam[],
@@ -436,7 +544,7 @@ function ruleForStage(
function roundRobinPairings( function roundRobinPairings(
teamCount: number, teamCount: number,
maxRounds?: number, maxRounds?: number,
): RoundRobinPairing[] { ): CanonicalRoundRobinPairing[] {
const bye = -1; const bye = -1;
const rotating = Array.from({ length: teamCount }, (_, index) => index); const rotating = Array.from({ length: teamCount }, (_, index) => index);
if (rotating.length % 2 === 1) rotating.push(bye); if (rotating.length % 2 === 1) rotating.push(bye);
@@ -449,7 +557,7 @@ function roundRobinPairings(
? Math.floor(maxRounds) ? Math.floor(maxRounds)
: fullRoundCount; : fullRoundCount;
const roundCount = Math.max(0, Math.min(fullRoundCount, requestedRounds)); 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 roundIndex = 0; roundIndex < roundCount; roundIndex += 1) {
for (let index = 0; index < rotating.length / 2; index += 1) { for (let index = 0; index < rotating.length / 2; index += 1) {
+1 -1
View File
@@ -274,7 +274,7 @@ Migration builds new collections without dual canonical writes.
`null`, mapping it to `pair`; an explicitly stored unknown mode remains `null`, mapping it to `pair`; an explicitly stored unknown mode remains
quarantined instead of being guessed. quarantined instead of being guessed.
- A persisted legacy round-robin `gameSchedule` is authoritative. Migration - 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 immutable Series graph reproduces the historical opponents and rounds instead of
generating a different canonical schedule. Matches without a persisted schedule generating a different canonical schedule. Matches without a persisted schedule
continue to use deterministic canonical round-robin generation. continue to use deterministic canonical round-robin generation.
+11 -13
View File
@@ -1,8 +1,5 @@
import type { TeamId } from "./ids.js"; import type { TeamId } from "./ids.js";
import type { import type { FirstToSeriesRule, FixedGamesSeriesRule } from "./series.js";
FirstToSeriesRule,
FixedGamesSeriesRule,
} from "./series.js";
export type CompetitionFormatType = export type CompetitionFormatType =
| "paired-series" | "paired-series"
@@ -14,20 +11,21 @@ export interface PairedSeriesCompetitionFormat {
rule: FixedGamesSeriesRule; rule: FixedGamesSeriesRule;
} }
export type RoundRobinTieBreaker = export type RoundRobinTieBreaker = "series-wins" | "game-diff" | "head-to-head";
| "series-wins"
| "game-diff" export interface RoundRobinPairing {
| "head-to-head"; roundNumber: number;
matchNumber: number;
teamAId: TeamId;
teamBId: TeamId;
}
export interface RoundRobinCompetitionFormat { export interface RoundRobinCompetitionFormat {
type: "round-robin"; type: "round-robin";
rule: FixedGamesSeriesRule; rule: FixedGamesSeriesRule;
maxRounds?: number; maxRounds?: number;
tieBreakers: [ pairings?: RoundRobinPairing[];
"series-wins", tieBreakers: ["series-wins", "game-diff", "head-to-head"];
"game-diff",
"head-to-head",
];
} }
export interface DoubleEliminationSeriesRules { export interface DoubleEliminationSeriesRules {
@@ -3,6 +3,7 @@ import type {
CompetitionId, CompetitionId,
CompletedSeriesProjection, CompletedSeriesProjection,
InProgressSeriesProjection, InProgressSeriesProjection,
RoundRobinCompetitionFormat,
SeriesOutcome, SeriesOutcome,
TeamId, TeamId,
} from "../src/index.js"; } from "../src/index.js";
@@ -26,3 +27,23 @@ export type InProgressSeriesCannotExposeOutcome = Expect<
export type LegacyBracketModeIsNotACompetitionFormat = Expect< export type LegacyBracketModeIsNotACompetitionFormat = Expect<
Not<IsAssignable<{ type: "bracket" }, CompetitionFormat>> Not<IsAssignable<{ type: "bracket" }, CompetitionFormat>>
>; >;
type ExplicitRoundRobinPairing = NonNullable<
RoundRobinCompetitionFormat["pairings"]
>[number];
export type ExplicitRoundRobinPairingsAreOptional = Expect<
IsAssignable<{}, Pick<RoundRobinCompetitionFormat, "pairings">>
>;
export type ExplicitRoundRobinPairingsAreTeamIdBased = Expect<
IsAssignable<
ExplicitRoundRobinPairing,
{
roundNumber: number;
matchNumber: number;
teamAId: TeamId;
teamBId: TeamId;
}
>
>;