release/86 #2

Merged
dahyeon merged 108 commits from release/86 into main 2026-07-15 08:56:05 +00:00
5 changed files with 347 additions and 34 deletions
Showing only changes of commit c2f89f9cb2 - Show all commits

No files matched your search

@@ -1,5 +1,18 @@
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', () => {
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 },
],
};
}
@@ -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<CompetitionGraphFormat, { type: 'round-robin' }>,
): 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<number, number>();
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<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(
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) {
+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
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.
+11 -13
View File
@@ -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 {
@@ -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<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;
}
>
>;