From 3b274b4ec2fefc1d9feba3c34fb8915fd144fd4f Mon Sep 17 00:00:00 2001 From: Park Dahyeon Date: Sun, 12 Jul 2026 19:08:10 +0000 Subject: [PATCH] feat: bootstrap competition aggregates from built teams --- .../competition-bootstrap.service.spec.ts | 508 ++++++++++++++ .../competition-bootstrap.service.ts | 623 ++++++++++++++++++ 2 files changed, 1131 insertions(+) create mode 100644 apps/api/src/modules/competition/competition-bootstrap.service.spec.ts create mode 100644 apps/api/src/modules/competition/competition-bootstrap.service.ts diff --git a/apps/api/src/modules/competition/competition-bootstrap.service.spec.ts b/apps/api/src/modules/competition/competition-bootstrap.service.spec.ts new file mode 100644 index 00000000..a35531aa --- /dev/null +++ b/apps/api/src/modules/competition/competition-bootstrap.service.spec.ts @@ -0,0 +1,508 @@ +import { Types } from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import { + CompetitionBootstrapError, + CompetitionBootstrapService, + type CompetitionBootstrapMatch, +} from './competition-bootstrap.service'; + +describe('CompetitionBootstrapService', () => { + it('creates a deterministic paired-Series Competition and immutable snapshots', async () => { + const firstHarness = createHarness(); + const firstService = new CompetitionBootstrapService( + firstHarness.connectionService as ConnectionService, + ); + const match = matchSnapshot({ gameMode: 'pair', teamCount: 2 }); + + const first = await firstService.bootstrap(match); + + const inserted = firstHarness.insertedPayloads[0]; + expect(inserted).toMatchObject({ + _id: expect.any(Types.ObjectId), + matchId: MATCH_ID, + communityId: COMMUNITY_ID, + schemaVersion: 1, + projectorVersion: 1, + revision: 0, + phase: 'ready', + format: { + type: 'paired-series', + rule: { type: 'fixed-games', gameCount: 3, drawPolicy: 'allow' }, + }, + }); + expect(inserted.teams).toEqual([ + expect.objectContaining({ + teamId: expect.any(Types.ObjectId), + legacyTeamIndex: 1, + displayOrder: 1, + seedNumber: 1, + name: 'Team 1', + members: [ + expect.objectContaining({ + userId: USER_IDS[0], + displayName: 'Player 1#KR1', + gameName: 'Player 1', + tagLine: 'KR1', + profileIconId: 101, + assignedPosition: 'TOP', + cost: 10, + }), + ], + }), + expect.objectContaining({ + teamId: expect.any(Types.ObjectId), + legacyTeamIndex: 2, + displayOrder: 2, + seedNumber: 2, + name: 'Team 2', + }), + ]); + expect(inserted.seriesGraph).toHaveLength(1); + expect(inserted.seriesGraph[0]).toMatchObject({ + code: 'PAIR_M1', + slots: [ + { + position: 'A', + source: { + type: 'team', + teamId: inserted.teams[0].teamId.toString(), + }, + }, + { + position: 'B', + source: { + type: 'team', + teamId: inserted.teams[1].teamId.toString(), + }, + }, + ], + }); + expect(inserted.projection).toMatchObject({ + competitionId: inserted._id.toString(), + sourceRevision: 0, + projectorVersion: 1, + formatType: 'paired-series', + phase: 'ready', + }); + expect(first._id).toEqual(inserted._id); + + const secondHarness = createHarness(); + const secondService = new CompetitionBootstrapService( + secondHarness.connectionService as ConnectionService, + ); + await secondService.bootstrap({ + ...match, + teams: [...match.teams].reverse(), + participants: [...match.participants].reverse(), + }); + + const secondInserted = secondHarness.insertedPayloads[0]; + expect(secondInserted._id).toEqual(inserted._id); + expect(secondInserted.teams.map(({ teamId }) => teamId)).toEqual( + inserted.teams.map(({ teamId }) => teamId), + ); + expect(secondInserted.seriesGraph).toEqual(inserted.seriesGraph); + }); + + it('maps round-robin configuration and preserves a limited round count', async () => { + const harness = createHarness(); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + + await service.bootstrap( + matchSnapshot({ + gameMode: 'round-robin', + teamCount: 4, + gameCount: 2, + roundRobinMaxRounds: 2, + }), + ); + + expect(harness.insertedPayloads[0]).toMatchObject({ + format: { + type: 'round-robin', + rule: { type: 'fixed-games', gameCount: 2, drawPolicy: 'allow' }, + maxRounds: 2, + tieBreakers: ['series-wins', 'game-diff', 'head-to-head'], + }, + }); + expect(harness.insertedPayloads[0].seriesGraph).toHaveLength(4); + }); + + it('maps double elimination seeds and stage-specific Series rules', async () => { + const harness = createHarness(); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + const match = matchSnapshot({ + gameMode: 'double-elimination', + teamCount: 4, + gameCount: 5, + }); + match.doubleElimination = { + teamCount: 4, + resetFinalEnabled: true, + seeds: [ + { seedNumber: 1, teamIndex: 3 }, + { seedNumber: 2, teamIndex: 1 }, + { seedNumber: 3, teamIndex: 4 }, + { seedNumber: 4, teamIndex: 2 }, + ], + }; + + await service.bootstrap(match); + + const inserted = harness.insertedPayloads[0]; + expect(inserted.format).toEqual({ + type: 'double-elimination', + teamCount: 4, + resetFinalEnabled: true, + rules: { + upper: { type: 'first-to', winsRequired: 3, maxGames: 5 }, + lower: { type: 'first-to', winsRequired: 1, maxGames: 1 }, + grandFinal: { type: 'first-to', winsRequired: 1, maxGames: 1 }, + resetFinal: { type: 'first-to', winsRequired: 1, maxGames: 1 }, + }, + }); + expect( + inserted.teams.map(({ legacyTeamIndex, seedNumber }) => ({ + legacyTeamIndex, + seedNumber, + })), + ).toEqual([ + { legacyTeamIndex: 1, seedNumber: 2 }, + { legacyTeamIndex: 2, seedNumber: 4 }, + { legacyTeamIndex: 3, seedNumber: 1 }, + { legacyTeamIndex: 4, seedNumber: 3 }, + ]); + expect( + inserted.seriesGraph.find(({ code }) => code === 'WB_R1_M1').rule, + ).toEqual({ type: 'first-to', winsRequired: 3, maxGames: 5 }); + expect( + inserted.seriesGraph.find(({ code }) => code?.startsWith('LB_')).rule, + ).toEqual({ type: 'first-to', winsRequired: 1, maxGames: 1 }); + expect(inserted.seriesGraph.find(({ code }) => code === 'GF').rule).toEqual( + { type: 'first-to', winsRequired: 1, maxGames: 1 }, + ); + expect( + inserted.seriesGraph.find(({ code }) => code === 'GF_RESET'), + ).toMatchObject({ + rule: { type: 'first-to', winsRequired: 1, maxGames: 1 }, + activation: { type: 'grand-final-reset-required' }, + }); + }); + + it('rejects incomplete and duplicate team assignments before opening a transaction', async () => { + const cases: Array<[string, (match: CompetitionBootstrapMatch) => void]> = [ + [ + 'an active participant is not assigned', + (match) => { + match.teams[1].members = []; + }, + ], + [ + 'the same team index is repeated', + (match) => { + match.teams[1].teamIndex = match.teams[0].teamIndex; + }, + ], + [ + 'one member is assigned to multiple teams', + (match) => { + match.teams[1].members[0].userId = match.teams[0].members[0].userId; + }, + ], + [ + 'a team member has no participant snapshot', + (match) => { + match.teams[1].members[0].userId = new Types.ObjectId(); + }, + ], + ]; + + for (const [label, mutate] of cases) { + const harness = createHarness(); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + const match = matchSnapshot({ gameMode: 'pair', teamCount: 2 }); + mutate(match); + + await expect(service.bootstrap(match)).rejects.toMatchObject({ + name: 'CompetitionBootstrapError', + code: 'INVALID_MATCH_TEAM_SNAPSHOT', + httpStatus: 422, + }); + expect(harness.connectionService.createSession).not.toHaveBeenCalled(); + expect(harness.competitionModel.findOneAndUpdate).not.toHaveBeenCalled(); + expect(label).toBeTruthy(); + } + }); + + it('rejects bracket mode live but explicitly maps it for legacy migration', async () => { + const liveHarness = createHarness(); + const liveService = new CompetitionBootstrapService( + liveHarness.connectionService as ConnectionService, + ); + const match = matchSnapshot({ gameMode: 'bracket', teamCount: 2 }); + + await expect(liveService.bootstrap(match)).rejects.toEqual( + expect.objectContaining>({ + code: 'UNSUPPORTED_LIVE_MATCH_MODE', + httpStatus: 422, + }), + ); + + const migrationHarness = createHarness(); + const migrationService = new CompetitionBootstrapService( + migrationHarness.connectionService as ConnectionService, + ); + await migrationService.bootstrap(match, { source: 'legacy-migration' }); + + expect(migrationHarness.insertedPayloads[0].format.type).toBe( + 'paired-series', + ); + }); + + it('upserts once and links only an unlinked or already-linked Match in one transaction', async () => { + const harness = createHarness(); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + + const competition = await service.bootstrap( + matchSnapshot({ gameMode: 'pair', teamCount: 2 }), + ); + + expect(harness.competitionModel.findOneAndUpdate).toHaveBeenCalledWith( + { matchId: MATCH_ID }, + { $setOnInsert: harness.insertedPayloads[0] }, + expect.objectContaining({ + upsert: true, + returnDocument: 'after', + setDefaultsOnInsert: true, + session: harness.sessions[0], + }), + ); + expect(harness.matchModel.updateOne).toHaveBeenCalledWith( + { + _id: MATCH_ID, + $or: [ + { competitionId: { $exists: false } }, + { competitionId: null }, + { competitionId: competition._id }, + ], + }, + { $set: { competitionId: competition._id } }, + { session: harness.sessions[0] }, + ); + expect(harness.sessions[0].commitTransaction).toHaveBeenCalledTimes(1); + expect(harness.sessions[0].abortTransaction).not.toHaveBeenCalled(); + expect(harness.sessions[0].endSession).toHaveBeenCalledTimes(1); + }); + + it('reuses an existing Competition without replacing its immutable snapshot', async () => { + const existingId = new Types.ObjectId('64b000000000000000000099'); + const existing = { + _id: existingId, + matchId: MATCH_ID, + teams: [{ name: 'Original immutable team snapshot' }], + revision: 4, + }; + const harness = createHarness({ existingCompetition: existing }); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + + const result = await service.bootstrap( + matchSnapshot({ gameMode: 'pair', teamCount: 2 }), + ); + + expect(result).toBe(existing); + expect(harness.competitionModel.findOneAndUpdate.mock.calls[0][1]).toEqual({ + $setOnInsert: harness.insertedPayloads[0], + }); + expect(harness.matchModel.updateOne.mock.calls[0][1]).toEqual({ + $set: { competitionId: existingId }, + }); + }); + + it('retries a duplicate-key bootstrap race and safely converges on the winner', async () => { + const duplicateKey = Object.assign(new Error('duplicate key'), { + code: 11000, + }); + const winner = { + _id: new Types.ObjectId('64b000000000000000000098'), + matchId: MATCH_ID, + revision: 0, + }; + const harness = createHarness({ + competitionResults: [duplicateKey, winner], + sessionCount: 2, + }); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + + const result = await service.bootstrap( + matchSnapshot({ gameMode: 'pair', teamCount: 2 }), + ); + + expect(result).toBe(winner); + expect(harness.connectionService.createSession).toHaveBeenCalledTimes(2); + expect(harness.sessions[0].abortTransaction).toHaveBeenCalledTimes(1); + expect(harness.sessions[0].commitTransaction).not.toHaveBeenCalled(); + expect(harness.sessions[0].endSession).toHaveBeenCalledTimes(1); + expect(harness.sessions[1].commitTransaction).toHaveBeenCalledTimes(1); + expect(harness.matchModel.updateOne).toHaveBeenCalledTimes(1); + }); + + it('aborts when the Match is already linked to a different Competition', async () => { + const harness = createHarness({ matchUpdateResult: { matchedCount: 0 } }); + const service = new CompetitionBootstrapService( + harness.connectionService as ConnectionService, + ); + + await expect( + service.bootstrap(matchSnapshot({ gameMode: 'pair', teamCount: 2 })), + ).rejects.toMatchObject({ + code: 'MATCH_COMPETITION_LINK_CONFLICT', + httpStatus: 409, + }); + expect(harness.sessions[0].abortTransaction).toHaveBeenCalledTimes(1); + expect(harness.sessions[0].commitTransaction).not.toHaveBeenCalled(); + }); +}); + +const MATCH_ID = new Types.ObjectId('64b000000000000000000001'); +const COMMUNITY_ID = new Types.ObjectId('64b000000000000000000002'); +const USER_IDS = Array.from( + { length: 8 }, + (_, index) => + new Types.ObjectId( + `64b0000000000000000001${String(index + 1).padStart(2, '0')}`, + ), +); + +function matchSnapshot(params: { + gameMode: CompetitionBootstrapMatch['gameMode']; + teamCount: number; + gameCount?: number; + roundRobinMaxRounds?: number; +}): CompetitionBootstrapMatch { + const participants = USER_IDS.slice(0, params.teamCount).map( + (userId, index) => ({ + userId, + gameName: `Player ${index + 1}`, + tagLine: 'KR1', + profileIconId: 101 + index, + preferredPositions: [], + joinedAt: new Date('2026-07-12T00:00:00.000Z'), + }), + ); + return { + _id: MATCH_ID, + communityId: COMMUNITY_ID, + gameCount: params.gameCount ?? 3, + gameMode: params.gameMode, + ...(params.roundRobinMaxRounds === undefined + ? {} + : { roundRobinMaxRounds: params.roundRobinMaxRounds }), + participants, + teams: participants.map((participant, index) => ({ + teamIndex: index + 1, + name: `Team ${index + 1}`, + captainUserId: participant.userId, + members: [ + { + userId: participant.userId, + assignedPosition: 'TOP', + cost: 10 + index, + }, + ], + })), + }; +} + +interface InsertPayload { + _id: Types.ObjectId; + teams: Array<{ + teamId: Types.ObjectId; + legacyTeamIndex: number; + seedNumber: number; + }>; + seriesGraph: Array<{ code?: string; rule: unknown }>; + [key: string]: any; +} + +function createHarness( + options: { + existingCompetition?: Record; + competitionResults?: Array | Error>; + matchUpdateResult?: { matchedCount: number }; + sessionCount?: number; + } = {}, +) { + const sessions = Array.from( + { length: options.sessionCount ?? 1 }, + createSession, + ); + const insertedPayloads: InsertPayload[] = []; + let competitionCall = 0; + const competitionModel = { + findOneAndUpdate: jest.fn( + ( + _filter: unknown, + update: { $setOnInsert: InsertPayload }, + _queryOptions: unknown, + ) => { + insertedPayloads.push(update.$setOnInsert); + const selected = options.competitionResults?.[competitionCall++]; + if (selected instanceof Error) return rejectedQuery(selected); + return queryResult( + selected ?? options.existingCompetition ?? update.$setOnInsert, + ); + }, + ), + }; + const matchModel = { + updateOne: jest + .fn() + .mockResolvedValue(options.matchUpdateResult ?? { matchedCount: 1 }), + }; + const models: Record = { + competition: competitionModel, + match: matchModel, + }; + let sessionIndex = 0; + const connectionService = { + createSession: jest.fn(() => Promise.resolve(sessions[sessionIndex++])), + getModel: jest.fn((name: string) => Promise.resolve(models[name])), + }; + + return { + sessions, + insertedPayloads, + competitionModel, + matchModel, + connectionService, + }; +} + +function createSession() { + return { + startTransaction: jest.fn(), + commitTransaction: jest.fn().mockResolvedValue(undefined), + abortTransaction: jest.fn().mockResolvedValue(undefined), + endSession: jest.fn().mockResolvedValue(undefined), + }; +} + +function queryResult(value: T) { + return { exec: jest.fn().mockResolvedValue(value) }; +} + +function rejectedQuery(error: Error) { + return { exec: jest.fn().mockRejectedValue(error) }; +} diff --git a/apps/api/src/modules/competition/competition-bootstrap.service.ts b/apps/api/src/modules/competition/competition-bootstrap.service.ts new file mode 100644 index 00000000..a0f33440 --- /dev/null +++ b/apps/api/src/modules/competition/competition-bootstrap.service.ts @@ -0,0 +1,623 @@ +import { createHash } from 'node:crypto'; +import { Injectable } from '@nestjs/common'; +import mongoose, { Types } from 'mongoose'; +import { ConnectionService } from '../global/database/connection.service'; +import type { + MatchGameMode, + MatchParticipant, + MatchTeam, +} from '../global/database/schema'; +import type { + CompetitionDocument, + CompetitionTeamSnapshot, +} from './competition.schema'; +import { + generateSeriesGraph, + type CompetitionGraphFormat, + type CompetitionGraphTeam, + type SeriesDefinition, +} from './domain/series-graph'; +import { + projectCompetition, + type CompetitionProjection, +} from './domain/competition-projector'; + +const COMPETITION_SCHEMA_VERSION = 1; +const COMPETITION_PROJECTOR_VERSION = 1; +const BOOTSTRAP_TRANSACTION_ATTEMPTS = 3; + +export interface CompetitionBootstrapMatch { + _id: Types.ObjectId; + communityId: Types.ObjectId; + competitionId?: Types.ObjectId; + gameCount: number; + gameMode: MatchGameMode; + roundRobinMaxRounds?: number; + participants: MatchParticipant[]; + teams: MatchTeam[]; + doubleElimination?: { + teamCount: 4 | 8; + resetFinalEnabled: boolean; + seeds: Array<{ seedNumber: number; teamIndex: number }>; + }; +} + +export interface CompetitionBootstrapOptions { + /** `bracket` is accepted only by the explicit legacy migration path. */ + source?: 'live' | 'legacy-migration'; +} + +export type CompetitionBootstrapErrorCode = + | 'INVALID_MATCH_TEAM_SNAPSHOT' + | 'INVALID_MATCH_FORMAT' + | 'UNSUPPORTED_LIVE_MATCH_MODE' + | 'COMPETITION_TRANSACTION_UNAVAILABLE' + | 'COMPETITION_BOOTSTRAP_FAILED' + | 'COMPETITION_BOOTSTRAP_RACE' + | 'MATCH_COMPETITION_LINK_CONFLICT'; + +export class CompetitionBootstrapError extends Error { + constructor( + public readonly code: CompetitionBootstrapErrorCode, + message: string, + public readonly httpStatus: 409 | 422 | 500, + public readonly details?: Readonly>, + ) { + super(message); + this.name = 'CompetitionBootstrapError'; + } +} + +interface CompetitionInsertPayload { + _id: Types.ObjectId; + matchId: Types.ObjectId; + communityId: Types.ObjectId; + schemaVersion: number; + projectorVersion: number; + revision: number; + phase: CompetitionProjection['phase']; + teams: CompetitionTeamSnapshot[]; + format: CompetitionGraphFormat; + seriesGraph: SeriesDefinition[]; + projection: CompetitionProjection; +} + +/** + * Freezes the recruiting Match into the one-to-one Competition aggregate. + * Retries only repeat deterministic upserts, so duplicate creators and unknown + * commit outcomes converge without replacing an existing immutable snapshot. + */ +@Injectable() +export class CompetitionBootstrapService { + constructor(private readonly connectionService: ConnectionService) {} + + public async bootstrap( + match: CompetitionBootstrapMatch, + options: CompetitionBootstrapOptions = {}, + ): Promise { + const payload = buildCompetitionInsertPayload( + match, + options.source ?? 'live', + ); + const [CompetitionModel, MatchModel] = await Promise.all([ + this.connectionService.getModel('competition'), + this.connectionService.getModel('match'), + ]); + + let lastRetryableError: unknown; + for ( + let attempt = 1; + attempt <= BOOTSTRAP_TRANSACTION_ATTEMPTS; + attempt += 1 + ) { + const session = await this.connectionService.createSession(); + if (!session) { + throw new CompetitionBootstrapError( + 'COMPETITION_TRANSACTION_UNAVAILABLE', + 'A MongoDB transaction is required to bootstrap a Competition.', + 500, + ); + } + + try { + session.startTransaction(); + const competition = await CompetitionModel.findOneAndUpdate( + { matchId: match._id }, + { $setOnInsert: payload }, + { + upsert: true, + returnDocument: 'after', + setDefaultsOnInsert: true, + session, + }, + ).exec(); + if (!competition) { + throw new CompetitionBootstrapError( + 'COMPETITION_BOOTSTRAP_FAILED', + 'Competition upsert returned no document.', + 500, + ); + } + + const linkResult = await MatchModel.updateOne( + { + _id: match._id, + $or: [ + { competitionId: { $exists: false } }, + { competitionId: null }, + { competitionId: competition._id }, + ], + }, + { $set: { competitionId: competition._id } }, + { session }, + ); + if (linkResult.matchedCount !== 1) { + throw new CompetitionBootstrapError( + 'MATCH_COMPETITION_LINK_CONFLICT', + 'Match is missing or linked to a different Competition.', + 409, + { matchId: match._id.toString() }, + ); + } + + await session.commitTransaction(); + return competition as CompetitionDocument; + } catch (error) { + await session.abortTransaction().catch(() => undefined); + if ( + attempt < BOOTSTRAP_TRANSACTION_ATTEMPTS && + isRetryableBootstrapError(error) + ) { + lastRetryableError = error; + continue; + } + if (isRetryableBootstrapError(error)) { + throw new CompetitionBootstrapError( + 'COMPETITION_BOOTSTRAP_RACE', + 'Competition bootstrap did not converge after concurrent writes.', + 409, + { matchId: match._id.toString() }, + ); + } + throw error; + } finally { + await session.endSession().catch(() => undefined); + } + } + + throw new CompetitionBootstrapError( + 'COMPETITION_BOOTSTRAP_RACE', + 'Competition bootstrap retry budget was exhausted.', + 409, + { + matchId: match._id.toString(), + cause: + lastRetryableError instanceof Error + ? lastRetryableError.message + : String(lastRetryableError), + }, + ); + } +} + +function buildCompetitionInsertPayload( + match: CompetitionBootstrapMatch, + source: NonNullable, +): CompetitionInsertPayload { + assertObjectId(match._id, 'Match ID'); + assertObjectId(match.communityId, 'Community ID'); + assertPositiveInteger(match.gameCount, 'Match game count'); + + const competitionId = stableObjectId(match._id, 'competition'); + const teams = snapshotTeams(match, competitionId); + const graphTeams = teams.map( + ({ teamId, displayOrder, seedNumber }): CompetitionGraphTeam => ({ + teamId: teamId.toString(), + displayOrder, + seedNumber, + }), + ); + const format = mapMatchFormat(match, teams, source); + + let seriesGraph: SeriesDefinition[]; + let projection: CompetitionProjection; + try { + seriesGraph = generateSeriesGraph({ + competitionId: competitionId.toString(), + teams: graphTeams, + format, + }); + projection = projectCompetition({ + competitionId: competitionId.toString(), + revision: 0, + projectorVersion: COMPETITION_PROJECTOR_VERSION, + teams: graphTeams, + format, + seriesGraph, + facts: [], + }); + } catch (error) { + throw new CompetitionBootstrapError( + 'INVALID_MATCH_FORMAT', + error instanceof Error + ? error.message + : 'The Match cannot produce a valid Competition graph.', + 422, + { + matchId: match._id.toString(), + domainCode: readErrorCode(error), + }, + ); + } + + return { + _id: competitionId, + matchId: match._id, + communityId: match.communityId, + schemaVersion: COMPETITION_SCHEMA_VERSION, + projectorVersion: COMPETITION_PROJECTOR_VERSION, + revision: 0, + phase: projection.phase, + teams, + format, + seriesGraph, + projection, + }; +} + +function snapshotTeams( + match: CompetitionBootstrapMatch, + competitionId: Types.ObjectId, +): CompetitionTeamSnapshot[] { + if (!Array.isArray(match.teams) || match.teams.length < 2) { + throw invalidTeamSnapshot( + 'A Competition requires at least two built teams.', + ); + } + if (!Array.isArray(match.participants)) { + throw invalidTeamSnapshot('Match participants are missing.'); + } + + const participantById = new Map(); + for (const participant of match.participants) { + const userId = objectIdString(participant?.userId); + if (!userId || participantById.has(userId)) { + throw invalidTeamSnapshot( + 'Match participants must have unique ObjectId user identities.', + ); + } + participantById.set(userId, participant); + } + + const orderedTeams = [...match.teams].sort( + (left, right) => left.teamIndex - right.teamIndex, + ); + const teamIndexes = new Set(); + const assignedUserIds = new Set(); + const memberCounts = new Set(); + const snapshots: CompetitionTeamSnapshot[] = []; + + for (const [displayIndex, team] of orderedTeams.entries()) { + if ( + !Number.isInteger(team.teamIndex) || + team.teamIndex < 1 || + teamIndexes.has(team.teamIndex) + ) { + throw invalidTeamSnapshot( + 'Built teams must have unique positive integer team indexes.', + ); + } + teamIndexes.add(team.teamIndex); + if (typeof team.name !== 'string' || team.name.trim().length === 0) { + throw invalidTeamSnapshot('Every built team needs a non-empty name.'); + } + if (!Array.isArray(team.members) || team.members.length === 0) { + throw invalidTeamSnapshot('Every built team needs at least one member.'); + } + memberCounts.add(team.members.length); + + const memberSnapshots = [...team.members] + .sort(compareTeamMembers) + .map((member) => { + const userId = objectIdString(member.userId); + const participant = userId ? participantById.get(userId) : undefined; + if ( + !userId || + !participant || + participant.excluded === true || + assignedUserIds.has(userId) + ) { + throw invalidTeamSnapshot( + 'Every non-excluded participant must be assigned to exactly one team.', + ); + } + assignedUserIds.add(userId); + + const gameName = nonEmptyString(participant.gameName); + const tagLine = nonEmptyString(participant.tagLine); + return { + userId: member.userId, + displayName: gameName + ? tagLine + ? `${gameName}#${tagLine}` + : gameName + : userId, + ...(gameName ? { gameName } : {}), + ...(tagLine ? { tagLine } : {}), + ...(participant.profileIconId === undefined + ? {} + : { profileIconId: participant.profileIconId }), + assignedPosition: member.assignedPosition, + ...(member.cost === undefined ? {} : { cost: member.cost }), + }; + }); + + if (team.captainUserId) { + const captainUserId = team.captainUserId.toString(); + if ( + !memberSnapshots.some( + ({ userId }) => userId.toString() === captainUserId, + ) + ) { + throw invalidTeamSnapshot('A team captain must belong to that team.'); + } + } + + snapshots.push({ + teamId: stableObjectId( + competitionId, + 'team', + `legacy-team-index:${team.teamIndex}`, + ), + legacyTeamIndex: team.teamIndex, + displayOrder: displayIndex + 1, + seedNumber: displayIndex + 1, + name: team.name.trim(), + ...(team.captainUserId ? { captainUserId: team.captainUserId } : {}), + members: memberSnapshots, + }); + } + + if (memberCounts.size !== 1) { + throw invalidTeamSnapshot( + 'All built teams must have the same member count.', + ); + } + const activeParticipantIds = [...participantById] + .filter(([, participant]) => participant.excluded !== true) + .map(([userId]) => userId); + if ( + activeParticipantIds.length !== assignedUserIds.size || + activeParticipantIds.some((userId) => !assignedUserIds.has(userId)) + ) { + throw invalidTeamSnapshot( + 'Every non-excluded participant must be assigned to exactly one team.', + ); + } + + applySeeds(match, snapshots); + return snapshots; +} + +function applySeeds( + match: CompetitionBootstrapMatch, + teams: CompetitionTeamSnapshot[], +): void { + if (match.gameMode !== 'double-elimination') return; + const configuredSeeds = match.doubleElimination?.seeds ?? []; + if (configuredSeeds.length === 0) return; + if (configuredSeeds.length !== teams.length) { + throw invalidTeamSnapshot( + 'Double-elimination seeds must include every built team exactly once.', + ); + } + + const validTeamIndexes = new Set( + teams.map(({ legacyTeamIndex }) => legacyTeamIndex as number), + ); + const seedByTeamIndex = new Map(); + const seedNumbers = new Set(); + for (const seed of configuredSeeds) { + if ( + !Number.isInteger(seed.seedNumber) || + seed.seedNumber < 1 || + seed.seedNumber > teams.length || + seedNumbers.has(seed.seedNumber) || + !validTeamIndexes.has(seed.teamIndex) || + seedByTeamIndex.has(seed.teamIndex) + ) { + throw invalidTeamSnapshot( + 'Double-elimination seeds must be unique and contiguous.', + ); + } + seedNumbers.add(seed.seedNumber); + seedByTeamIndex.set(seed.teamIndex, seed.seedNumber); + } + for (const team of teams) { + team.seedNumber = seedByTeamIndex.get(team.legacyTeamIndex as number)!; + } +} + +function mapMatchFormat( + match: CompetitionBootstrapMatch, + teams: CompetitionTeamSnapshot[], + source: NonNullable, +): CompetitionGraphFormat { + switch (match.gameMode) { + case 'pair': + return fixedGameFormat('paired-series', match.gameCount); + case 'bracket': + if (source !== 'legacy-migration') { + throw new CompetitionBootstrapError( + 'UNSUPPORTED_LIVE_MATCH_MODE', + 'Legacy bracket mode can only be bootstrapped by migration.', + 422, + ); + } + return fixedGameFormat('paired-series', match.gameCount); + case 'round-robin': + if ( + match.roundRobinMaxRounds !== undefined && + (!Number.isInteger(match.roundRobinMaxRounds) || + match.roundRobinMaxRounds < 1) + ) { + throw new CompetitionBootstrapError( + 'INVALID_MATCH_FORMAT', + 'Round-robin max rounds must be a positive integer.', + 422, + ); + } + return { + type: 'round-robin', + rule: fixedGamesRule(match.gameCount), + ...(match.roundRobinMaxRounds === undefined + ? {} + : { maxRounds: match.roundRobinMaxRounds }), + tieBreakers: ['series-wins', 'game-diff', 'head-to-head'], + }; + case 'double-elimination': { + if (teams.length !== 4 && teams.length !== 8) { + throw new CompetitionBootstrapError( + 'INVALID_MATCH_FORMAT', + 'Double elimination supports only four or eight teams.', + 422, + ); + } + if ( + match.doubleElimination?.teamCount !== undefined && + match.doubleElimination.teamCount !== teams.length + ) { + throw new CompetitionBootstrapError( + 'INVALID_MATCH_FORMAT', + 'Double-elimination team count does not match the built teams.', + 422, + ); + } + const bestOfOne = { + type: 'first-to' as const, + winsRequired: 1, + maxGames: 1, + }; + return { + type: 'double-elimination', + teamCount: teams.length, + resetFinalEnabled: match.doubleElimination?.resetFinalEnabled ?? false, + rules: { + upper: { + type: 'first-to', + winsRequired: Math.floor(match.gameCount / 2) + 1, + maxGames: match.gameCount, + }, + lower: { ...bestOfOne }, + grandFinal: { ...bestOfOne }, + resetFinal: { ...bestOfOne }, + }, + }; + } + } +} + +function fixedGameFormat( + type: 'paired-series', + gameCount: number, +): Extract { + return { type, rule: fixedGamesRule(gameCount) }; +} + +function fixedGamesRule(gameCount: number) { + return { + type: 'fixed-games' as const, + gameCount, + drawPolicy: 'allow' as const, + }; +} + +function stableObjectId( + namespaceId: Types.ObjectId, + entityKind: string, + ...logicalKey: string[] +): Types.ObjectId { + const hex = createHash('sha256') + .update(JSON.stringify([namespaceId.toString(), entityKind, ...logicalKey])) + .digest('hex') + .slice(0, 24); + return new Types.ObjectId(hex); +} + +function compareTeamMembers( + left: MatchTeam['members'][number], + right: MatchTeam['members'][number], +): number { + const positionOrder = ['TOP', 'JGL', 'MID', 'ADC', 'SUP']; + return ( + positionOrder.indexOf(left.assignedPosition) - + positionOrder.indexOf(right.assignedPosition) || + left.userId.toString().localeCompare(right.userId.toString()) + ); +} + +function invalidTeamSnapshot(message: string): CompetitionBootstrapError { + return new CompetitionBootstrapError( + 'INVALID_MATCH_TEAM_SNAPSHOT', + message, + 422, + ); +} + +function assertPositiveInteger(value: number, label: string): void { + if (!Number.isInteger(value) || value < 1) { + throw new CompetitionBootstrapError( + 'INVALID_MATCH_FORMAT', + `${label} must be a positive integer.`, + 422, + ); + } +} + +function assertObjectId( + value: unknown, + label: string, +): asserts value is Types.ObjectId { + if (!(value instanceof mongoose.Types.ObjectId)) { + throw invalidTeamSnapshot(`${label} must be a MongoDB ObjectId.`); + } +} + +function objectIdString(value: unknown): string | undefined { + return value instanceof mongoose.Types.ObjectId + ? value.toString() + : undefined; +} + +function nonEmptyString(value: unknown): string | undefined { + if (typeof value !== 'string') return undefined; + const trimmed = value.trim(); + return trimmed.length > 0 ? trimmed : undefined; +} + +function readErrorCode(error: unknown): string | undefined { + if ( + typeof error === 'object' && + error !== null && + 'code' in error && + typeof error.code === 'string' + ) { + return error.code; + } + return undefined; +} + +function isRetryableBootstrapError(error: unknown): boolean { + const candidate = error as { + code?: number; + codeName?: string; + hasErrorLabel?: (label: string) => boolean; + }; + return Boolean( + candidate?.code === 11000 || + candidate?.code === 112 || + candidate?.codeName === 'WriteConflict' || + candidate?.hasErrorLabel?.('TransientTransactionError') || + candidate?.hasErrorLabel?.('UnknownTransactionCommitResult'), + ); +}