import { createHash } from 'node:crypto'; import mongoose from 'mongoose'; import { projectCompetition } from '../../../competition/domain/competition-projector'; import { COMPETITION_DOMAIN_INVARIANT_INDEXES, type CompetitionDomainInvariantIndex, } from '../../../competition/competition.schema'; import { planCompetitionMigration, type CompetitionMigrationAssignment, type CompetitionMigrationFact, type CompetitionMigrationIssue, type LegacyMatchInput, type ReadyCompetitionMigrationPlan, } from './20260712-competition-domain'; const DEFAULT_MIGRATION_RUN_ID = '20260712-competition-domain'; const MATCH_SCAN_FILTER = { 'teams.1': { $exists: true } }; type AnyDocument = Record & { _id: unknown }; export interface CompetitionDomainMigrationCursor extends AsyncIterable { sort(specification: Record): CompetitionDomainMigrationCursor; limit(limit: number): CompetitionDomainMigrationCursor; } export interface CompetitionDomainMigrationCollection { createIndex( key: mongoose.IndexDefinition, options: mongoose.IndexOptions, ): Promise; find( filter: Record, options?: { session?: CompetitionDomainMigrationSession }, ): CompetitionDomainMigrationCursor; findOne( filter: Record, options?: { session?: CompetitionDomainMigrationSession }, ): Promise; updateOne( filter: Record, update: { $set?: Record; $setOnInsert?: Record; $unset?: Record; }, options?: { session?: CompetitionDomainMigrationSession; upsert?: boolean; }, ): Promise<{ matchedCount?: number; modifiedCount?: number; upsertedCount?: number; }>; deleteOne( filter: Record, options?: { session?: CompetitionDomainMigrationSession }, ): Promise<{ deletedCount?: number }>; } export interface CompetitionDomainMigrationDb { collection(name: string): CompetitionDomainMigrationCollection; } export interface CompetitionDomainMigrationSession { startTransaction(): void; commitTransaction(): Promise; abortTransaction(): Promise; endSession(): Promise; } export interface CompetitionDomainMigrationOptions { dryRun?: boolean; limit?: number; afterMatchId?: string; migrationRunId?: string; now?: Date; startSession?: () => Promise; onProgress?: (progress: CompetitionDomainMigrationProgress) => void; } export interface CompetitionDomainMigrationProgress { index: number; matchId: string; status: CompetitionDomainMigrationMatchResult['status']; total: number; } interface CompetitionDomainMigrationMatchBase { matchId: string; competitionId?: string; warnings: CompetitionMigrationIssue[]; } export type CompetitionDomainMigrationMatchResult = | (CompetitionDomainMigrationMatchBase & { status: 'ready' | 'applied'; factCount: number; assignmentCount: number; }) | (CompetitionDomainMigrationMatchBase & { status: 'already-applied'; }) | (CompetitionDomainMigrationMatchBase & { status: 'quarantined'; reasons: CompetitionMigrationIssue[]; }) | (CompetitionDomainMigrationMatchBase & { status: 'failed'; error: string; }); export interface CompetitionDomainMigrationSummary { scanned: number; ready: number; applied: number; alreadyApplied: number; quarantined: number; failed: number; /** Planner/runtime failures that were neither ready nor explicitly quarantined. */ unclassified: number; factsPlanned: number; assignmentsPlanned: number; warnings: number; } export interface CompetitionDomainMigrationResult { migrationRunId: string; mode: 'dry-run' | 'apply'; indexPreflight: CompetitionDomainIndexPreflight; resume: CompetitionDomainMigrationResume; summary: CompetitionDomainMigrationSummary; matches: CompetitionDomainMigrationMatchResult[]; } export interface CompetitionDomainMigrationResume { strategy: 'none' | 'cursor' | 'checkpoint'; startedAfterMatchId?: string; checkpointAfterMatchId?: string; hasMore: boolean; completed: boolean; } export interface CompetitionDomainIndexConflict { collection: CompetitionDomainInvariantIndex['collection']; indexName: string; key: Record; code?: number; keyPattern?: Record; keyValue?: unknown; message: string; } export interface CompetitionDomainIndexPreflight { status: 'dry-run' | 'ensured' | 'blocked'; requiredIndexes: number; ensuredIndexes: string[]; conflicts: CompetitionDomainIndexConflict[]; } /** * Plans or applies the clean-break Competition migration. Apply mode owns one * Mongo transaction per Match so a process can be stopped and safely resumed. */ export async function migrateCompetitionDomain( db: CompetitionDomainMigrationDb, options: CompetitionDomainMigrationOptions = {}, ): Promise { const dryRun = options.dryRun ?? true; const migrationRunId = options.migrationRunId?.trim() || DEFAULT_MIGRATION_RUN_ID; assertOptions(options); const resumeStart = await resolveResumeStart( db, migrationRunId, options, dryRun, ); const indexPreflight = await ensureCompetitionDomainIndexes(db, dryRun); if (indexPreflight.status === 'blocked') { return { migrationRunId, mode: 'apply', indexPreflight, resume: resumeReport(resumeStart, undefined, true, false), summary: summarize([]), matches: [], }; } if (!dryRun && options.limit !== undefined && options.afterMatchId) { await persistMigrationCheckpoint(db, { migrationRunId, matchId: options.afterMatchId, completed: false, resetMatchStatus: true, observedAt: options.now ?? new Date(), }); } const scan = await scanMatches( db, options.limit, resumeStart.startedAfterMatchId, ); const matches: CompetitionDomainMigrationMatchResult[] = []; let checkpointAfterMatchId = resumeStart.startedAfterMatchId; let haltedOnFailure = false; for (const [index, scannedMatch] of scan.matches.entries()) { const result = dryRun ? await inspectMatch(db, scannedMatch, migrationRunId) : await applyMatch(db, scannedMatch, migrationRunId, options); matches.push(result); options.onProgress?.({ index: index + 1, matchId: result.matchId, status: result.status, total: scan.matches.length, }); if (!dryRun && options.limit !== undefined) { if (result.status === 'failed') { haltedOnFailure = true; break; } await persistMigrationCheckpoint(db, { migrationRunId, matchId: result.matchId, matchStatus: result.status, completed: false, observedAt: options.now ?? new Date(), }); checkpointAfterMatchId = result.matchId; } } const hasMore = scan.hasMore || haltedOnFailure || matches.length < scan.matches.length; const completed = !hasMore && !matches.some(({ status }) => status === 'failed'); if (!dryRun && options.limit !== undefined && completed) { await persistMigrationCheckpoint(db, { migrationRunId, matchId: checkpointAfterMatchId, completed: true, observedAt: options.now ?? new Date(), }); } return { migrationRunId, mode: dryRun ? 'dry-run' : 'apply', indexPreflight, resume: resumeReport( resumeStart, checkpointAfterMatchId, hasMore, completed, ), summary: summarize(matches), matches, }; } interface ResumeStart { strategy: CompetitionDomainMigrationResume['strategy']; startedAfterMatchId?: string; } async function resolveResumeStart( db: CompetitionDomainMigrationDb, migrationRunId: string, options: CompetitionDomainMigrationOptions, dryRun: boolean, ): Promise { if (dryRun || options.limit === undefined) { return { strategy: options.afterMatchId ? 'cursor' : 'none', ...(options.afterMatchId ? { startedAfterMatchId: options.afterMatchId } : {}), }; } if (options.afterMatchId) { return { strategy: 'cursor', startedAfterMatchId: options.afterMatchId, }; } const checkpoint = await db .collection('competition_migration_checkpoint') .findOne({ _id: migrationRunId }); const checkpointMatchId = optionalIdString(checkpoint?.lastMatchId); if (checkpointMatchId) assertMatchCursor(checkpointMatchId); return { strategy: 'checkpoint', ...(checkpointMatchId ? { startedAfterMatchId: checkpointMatchId } : {}), }; } function resumeReport( start: ResumeStart, checkpointAfterMatchId: string | undefined, hasMore: boolean, completed: boolean, ): CompetitionDomainMigrationResume { return { strategy: start.strategy, ...(start.startedAfterMatchId ? { startedAfterMatchId: start.startedAfterMatchId } : {}), ...(checkpointAfterMatchId ? { checkpointAfterMatchId } : {}), hasMore, completed, }; } async function persistMigrationCheckpoint( db: CompetitionDomainMigrationDb, params: { migrationRunId: string; matchId?: string; matchStatus?: CompetitionDomainMigrationMatchResult['status']; completed: boolean; resetMatchStatus?: boolean; observedAt: Date; }, ): Promise { await db.collection('competition_migration_checkpoint').updateOne( { _id: params.migrationRunId }, { $set: { migrationRunId: params.migrationRunId, status: params.completed ? 'completed' : 'running', ...(params.matchId ? { lastMatchId: persistenceId(params.matchId) } : {}), ...(params.matchStatus ? { lastMatchStatus: params.matchStatus } : {}), updatedAt: params.observedAt, }, $setOnInsert: { _id: params.migrationRunId, createdAt: params.observedAt, }, ...(params.resetMatchStatus ? { $unset: { lastMatchStatus: 1 } } : {}), }, { upsert: true }, ); } async function ensureCompetitionDomainIndexes( db: CompetitionDomainMigrationDb, dryRun: boolean, ): Promise { if (dryRun) { return { status: 'dry-run', requiredIndexes: COMPETITION_DOMAIN_INVARIANT_INDEXES.length, ensuredIndexes: [], conflicts: [], }; } const ensuredIndexes: string[] = []; const conflicts: CompetitionDomainIndexConflict[] = []; for (const index of COMPETITION_DOMAIN_INVARIANT_INDEXES) { try { const createdName = await db .collection(index.collection) .createIndex(index.key, index.options); ensuredIndexes.push(createdName); } catch (error) { conflicts.push(indexConflict(index, error)); } } return { status: conflicts.length > 0 ? 'blocked' : 'ensured', requiredIndexes: COMPETITION_DOMAIN_INVARIANT_INDEXES.length, ensuredIndexes, conflicts, }; } function indexConflict( index: CompetitionDomainInvariantIndex, error: unknown, ): CompetitionDomainIndexConflict { const record = isRecord(error) ? error : {}; const code = typeof record.code === 'number' && Number.isInteger(record.code) ? record.code : undefined; const keyPattern = isRecord(record.keyPattern) ? (canonicalValue(record.keyPattern) as Record) : undefined; const keyValue = record.keyValue === undefined ? undefined : canonicalValue(record.keyValue); return { collection: index.collection, indexName: index.options.name, key: canonicalValue(index.key) as Record, ...(code === undefined ? {} : { code }), ...(keyPattern ? { keyPattern } : {}), ...(keyValue === undefined ? {} : { keyValue }), message: error instanceof Error ? error.message : String(error), }; } async function scanMatches( db: CompetitionDomainMigrationDb, limit: number | undefined, afterMatchId: string | undefined, ): Promise<{ matches: AnyDocument[]; hasMore: boolean }> { const scanned = await readCursor( db .collection('match') .find({ ...MATCH_SCAN_FILTER, ...(afterMatchId ? { _id: { $gt: persistenceId(afterMatchId) } } : {}), }) .sort({ _id: 1 }) .limit(limit === undefined ? 0 : limit + 1), ); if (limit === undefined) return { matches: scanned, hasMore: false }; return { matches: scanned.slice(0, limit), hasMore: scanned.length > limit, }; } async function inspectMatch( db: CompetitionDomainMigrationDb, scannedMatch: AnyDocument, migrationRunId: string, ): Promise { const matchId = idString(scannedMatch._id); try { const linkedCompetitionId = optionalIdString(scannedMatch.competitionId); if (linkedCompetitionId) { assertExpectedCompetitionId(matchId, linkedCompetitionId); await verifyProjectionReplay(db, linkedCompetitionId); return { status: 'already-applied', matchId, competitionId: linkedCompetitionId, warnings: [], }; } const legacy = await hydrateLegacyMatch(db, scannedMatch); const plan = planCompetitionMigration(legacy, { migrationRunId }); return planResult(matchId, plan); } catch (error) { return failedResult(matchId, error); } } async function applyMatch( db: CompetitionDomainMigrationDb, scannedMatch: AnyDocument, migrationRunId: string, options: CompetitionDomainMigrationOptions, ): Promise { const matchId = idString(scannedMatch._id); let session: CompetitionDomainMigrationSession | undefined; try { session = await options.startSession?.(); if (!session) { throw new Error( 'Apply mode requires a MongoDB transaction session for every Match.', ); } session.startTransaction(); const currentMatch = await db .collection('match') .findOne({ _id: scannedMatch._id }, { session }); if (!currentMatch) throw new Error(`Match ${matchId} no longer exists.`); const linkedCompetitionId = optionalIdString(currentMatch.competitionId); if (linkedCompetitionId) { assertExpectedCompetitionId(matchId, linkedCompetitionId); await verifyProjectionReplay(db, linkedCompetitionId, session); await db .collection('competition_migration_quarantine') .deleteOne({ _id: currentMatch._id }, { session }); await verifyProjectionReplay(db, linkedCompetitionId, session); await session.commitTransaction(); return { status: 'already-applied', matchId, competitionId: linkedCompetitionId, warnings: [], }; } // Re-read all evidence inside the transaction. The scan is only a work // list; it is never treated as the source snapshot for an apply. const legacy = await hydrateLegacyMatch(db, currentMatch, session); const plan = planCompetitionMigration(legacy, { migrationRunId }); if (plan.status === 'quarantined') { await persistQuarantine( db, currentMatch, plan.reasons, plan.warnings, migrationRunId, options.now ?? new Date(), session, ); await session.commitTransaction(); return { status: 'quarantined', matchId, warnings: plan.warnings, reasons: plan.reasons, }; } const uniquenessConflicts = await findReadyPlanUniquenessConflicts( db, plan, session, ); if (uniquenessConflicts.length > 0) { await persistQuarantine( db, currentMatch, uniquenessConflicts, plan.warnings, migrationRunId, options.now ?? new Date(), session, ); await session.commitTransaction(); return { status: 'quarantined', matchId, warnings: plan.warnings, reasons: uniquenessConflicts, }; } await upsertReadyPlan(db, plan, session); await verifyReadyPlan(db, plan, session); const competitionId = plan.competition.id; const linkResult = await db.collection('match').updateOne( { _id: currentMatch._id, $or: [ { competitionId: { $exists: false } }, { competitionId: null }, { competitionId: persistenceId(competitionId) }, ], }, { $set: { competitionId: persistenceId(competitionId) } }, { session }, ); if (linkResult.matchedCount !== 1) { throw new Error( `Match ${matchId} was concurrently linked to another Competition.`, ); } await db .collection('competition_migration_quarantine') .deleteOne({ _id: currentMatch._id }, { session }); // Verify again after the final Match/quarantine writes, immediately before // committing, so every applied Match ends with a replay-equal aggregate. await verifyProjectionReplay(db, competitionId, session); await session.commitTransaction(); return { status: 'applied', matchId, competitionId, factCount: plan.facts.length, assignmentCount: plan.assignments.length, warnings: plan.warnings, }; } catch (error) { if (session) await session.abortTransaction().catch(() => undefined); return failedResult(matchId, error); } finally { if (session) await session.endSession().catch(() => undefined); } } interface UniqueIdentityCheck { collection: 'competition' | 'competition_fact' | 'tournament_code_assignment'; indexName: string; filter: Record; expectedDocumentId: string; } async function findReadyPlanUniquenessConflicts( db: CompetitionDomainMigrationDb, plan: ReadyCompetitionMigrationPlan, session: CompetitionDomainMigrationSession, ): Promise { const checks: UniqueIdentityCheck[] = [ { collection: 'competition', indexName: 'matchId_1', filter: { matchId: persistenceId(plan.competition.matchId) }, expectedDocumentId: plan.competition.id, }, ]; for (const fact of plan.facts) { checks.push( { collection: 'competition_fact', indexName: 'competitionId_1_revision_1_ordinalWithinRevision_1', filter: { competitionId: persistenceId(fact.competitionId), revision: fact.revision, ordinalWithinRevision: fact.ordinalWithinRevision, }, expectedDocumentId: fact.id, }, { collection: 'competition_fact', indexName: 'competitionId_1_commandId_1_ordinalWithinRevision_1', filter: { competitionId: persistenceId(fact.competitionId), commandId: fact.commandId, ordinalWithinRevision: fact.ordinalWithinRevision, }, expectedDocumentId: fact.id, }, ); if (fact.type === 'game-accepted' && fact.evidence.type === 'riot') { checks.push({ collection: 'competition_fact', indexName: 'evidence.riotMatchId_1', filter: { type: 'game-accepted', 'evidence.riotMatchId': fact.evidence.riotMatchId, }, expectedDocumentId: fact.id, }); } } for (const assignment of plan.assignments) { if (assignment.state === 'reserved' || assignment.state === 'used') { checks.push( { collection: 'tournament_code_assignment', indexName: 'gameSlotId_1', filter: { gameSlotId: persistenceId(assignment.gameSlotId), state: { $in: ['reserved', 'used'] }, }, expectedDocumentId: assignment.id, }, { collection: 'tournament_code_assignment', indexName: 'tournamentCodeId_1', filter: { tournamentCodeId: persistenceId(assignment.tournamentCodeId), state: { $in: ['reserved', 'used'] }, }, expectedDocumentId: assignment.id, }, ); } if (assignment.riotMatchId) { checks.push({ collection: 'tournament_code_assignment', indexName: 'riotMatchId_1', filter: { riotMatchId: assignment.riotMatchId }, expectedDocumentId: assignment.id, }); } } const conflicts: CompetitionMigrationIssue[] = []; // Mongo sessions do not support parallel operations inside one transaction. for (const check of checks) { const existing = await db .collection(check.collection) .findOne(check.filter, { session }); if (!existing || idString(existing._id) === check.expectedDocumentId) { continue; } conflicts.push({ code: 'GLOBAL_UNIQUE_INDEX_CONFLICT', message: `Migration input conflicts with ${check.collection}.${check.indexName}.`, details: { collection: check.collection, indexName: check.indexName, key: canonicalValue(check.filter) as Record, expectedDocumentId: check.expectedDocumentId, conflictingDocumentId: idString(existing._id), ...(existing.competitionId ? { conflictingCompetitionId: idString(existing.competitionId) } : {}), }, }); } return conflicts; } async function hydrateLegacyMatch( db: CompetitionDomainMigrationDb, match: AnyDocument, session?: CompetitionDomainMigrationSession, ): Promise { const tournamentCodeIds = arrayOf(match.tournamentCodeIds); const tournamentCodes = await readCursor( db .collection('tournamentCode') .find( { $or: [ ...(tournamentCodeIds.length > 0 ? [{ _id: { $in: tournamentCodeIds } }] : []), { matchId: match._id }, ], }, { session }, ) .sort({ _id: 1 }) .limit(0), ); const result = isRecord(match.result) ? match.result : undefined; const games = arrayOf(result?.games); const riotMatchIds = uniqueStrings( games.map((game) => (isRecord(game) ? game.riotMatchId : undefined)), ); const archives = riotMatchIds.length === 0 ? [] : await readCursor( db .collection('riotMatch') .find({ matchId: { $in: riotMatchIds } }, { session }) .sort({ matchId: 1 }) .limit(0), ); const archiveByMatchId = new Map( archives.map((archive) => [String(archive.matchId), archive]), ); const archivedIds = new Set(archiveByMatchId.keys()); const hydratedResult = result ? { ...result, games: games.map((game) => isRecord(game) ? hydrateLegacyGameEvidence(game, archiveByMatchId) : game, ), } : undefined; return { ...match, // Native collection reads bypass the MatchSchema default. Historical // documents without a persisted gameMode still executed as pair mode via // the runtime fallback. gameMode: match.gameMode ?? 'pair', ...(hydratedResult ? { result: hydratedResult } : {}), tournamentCodes, riotMatchArchiveIds: [...archivedIds].sort(), } as unknown as LegacyMatchInput; } function hydrateLegacyGameEvidence( game: Record, archiveByMatchId: ReadonlyMap, ): Record { const riotMatchId = typeof game.riotMatchId === 'string' ? game.riotMatchId : undefined; const archive = riotMatchId ? archiveByMatchId.get(riotMatchId) : undefined; if (!archive) return { ...game, riotArchivePresent: false }; const existingPayloadHash = typeof game.payloadHash === 'string' && game.payloadHash.trim().length > 0 ? game.payloadHash : undefined; return { ...game, riotArchivePresent: true, payloadHash: existingPayloadHash ?? `sha256:${createNodeHash(canonicalJson(archive.raw ?? archive))}`, }; } async function upsertReadyPlan( db: CompetitionDomainMigrationDb, plan: ReadyCompetitionMigrationPlan, session: CompetitionDomainMigrationSession, ): Promise { const competition = competitionForPersistence(plan); await db .collection('competition') .updateOne( { _id: competition._id }, { $setOnInsert: competition }, { upsert: true, session }, ); for (const fact of plan.facts) { const persisted = factForPersistence(fact); await db .collection('competition_fact') .updateOne( { _id: persisted._id }, { $setOnInsert: persisted }, { upsert: true, session }, ); } for (const assignment of plan.assignments) { const persisted = assignmentForPersistence(assignment); await db .collection('tournament_code_assignment') .updateOne( { _id: persisted._id }, { $setOnInsert: persisted }, { upsert: true, session }, ); } } async function verifyReadyPlan( db: CompetitionDomainMigrationDb, plan: ReadyCompetitionMigrationPlan, session: CompetitionDomainMigrationSession, ): Promise { const competition = await db .collection('competition') .findOne({ _id: persistenceId(plan.competition.id) }, { session }); if (!competition) { throw new Error( `Competition ${plan.competition.id} is missing after deterministic upsert.`, ); } assertFieldsEqual( competition, competitionForPersistence(plan), [ '_id', 'matchId', 'communityId', 'schemaVersion', 'projectorVersion', 'teams', 'format', 'seriesGraph', ], `Competition ${plan.competition.id}`, ); for (const fact of plan.facts) { const expected = factForPersistence(fact); const actual = await db .collection('competition_fact') .findOne({ _id: expected._id }, { session }); if (!actual) throw new Error(`Migration fact ${fact.id} is missing.`); assertFieldsEqual( actual, expected, Object.keys(expected).filter( (key) => key !== 'createdAt' && key !== 'updatedAt', ), `Migration fact ${fact.id}`, ); } for (const assignment of plan.assignments) { const expected = assignmentForPersistence(assignment); const actual = await db .collection('tournament_code_assignment') .findOne({ _id: expected._id }, { session }); if (!actual) { throw new Error(`TournamentCode assignment ${assignment.id} is missing.`); } assertFieldsEqual( actual, expected, Object.keys(expected).filter( (key) => key !== 'createdAt' && key !== 'updatedAt', ), `TournamentCode assignment ${assignment.id}`, ); } await verifyProjectionReplay(db, plan.competition.id, session); } async function verifyProjectionReplay( db: CompetitionDomainMigrationDb, competitionId: string, session?: CompetitionDomainMigrationSession, ): Promise { const competition = await db .collection('competition') .findOne({ _id: persistenceId(competitionId) }, { session }); if (!competition) { throw new Error(`Linked Competition ${competitionId} does not exist.`); } const facts = await readCursor( db .collection('competition_fact') .find({ competitionId: persistenceId(competitionId) }, { session }) .sort({ revision: 1, ordinalWithinRevision: 1 }) .limit(0), ); const revision = numberField(competition, 'revision'); const projectorVersion = numberField(competition, 'projectorVersion'); assertLedgerRevision(facts, revision, competitionId); const replay = projectCompetition({ competitionId, revision, projectorVersion, teams: canonicalValue(competition.teams) as never, format: canonicalValue(competition.format) as never, seriesGraph: canonicalValue(competition.seriesGraph) as never, facts: facts.map(factForProjection), }); if (canonicalJson(replay) !== canonicalJson(competition.projection)) { throw new Error( `Competition ${competitionId} projection replay does not equal the persisted projection.`, ); } if (replay.phase !== competition.phase) { throw new Error( `Competition ${competitionId} replay phase does not equal the persisted phase.`, ); } } function assertLedgerRevision( facts: ReadonlyArray>, competitionRevision: number, competitionId: string, ): void { const positions = new Set(); const revisions = new Set(); let maximumRevision = 0; for (const fact of facts) { const revision = numberField(fact, 'revision'); const ordinal = numberField(fact, 'ordinalWithinRevision'); if (revision < 1 || ordinal < 1) { throw new Error( `Competition ${competitionId} has an invalid fact ledger position.`, ); } const position = `${revision}:${ordinal}`; if (positions.has(position)) { throw new Error( `Competition ${competitionId} has duplicate fact ledger position ${position}.`, ); } positions.add(position); revisions.add(revision); maximumRevision = Math.max(maximumRevision, revision); } if (maximumRevision !== competitionRevision) { throw new Error( `Competition ${competitionId} revision ${competitionRevision} does not match fact ledger revision ${maximumRevision}.`, ); } if (revisions.size !== maximumRevision) { throw new Error( `Competition ${competitionId} fact ledger has a revision gap.`, ); } } async function persistQuarantine( db: CompetitionDomainMigrationDb, match: AnyDocument, reasons: CompetitionMigrationIssue[], warnings: CompetitionMigrationIssue[], migrationRunId: string, observedAt: Date, session: CompetitionDomainMigrationSession, ): Promise { const sourceUpdatedAt = dateOrUndefined(match.updatedAt); const payload = { matchId: match._id, migrationRunId, status: 'quarantined', reasons, warnings, sourceUpdatedAt, planHash: canonicalHash({ matchId: idString(match._id), sourceUpdatedAt, reasons, warnings, }), observedAt, updatedAt: observedAt, }; await db.collection('competition_migration_quarantine').updateOne( { _id: match._id }, { $set: payload, $setOnInsert: { _id: match._id, createdAt: observedAt }, }, { upsert: true, session }, ); } function competitionForPersistence( plan: ReadyCompetitionMigrationPlan, ): AnyDocument { const source = plan.competition; return { _id: persistenceId(source.id), matchId: persistenceId(source.matchId), communityId: persistenceId(source.communityId), schemaVersion: source.schemaVersion, projectorVersion: source.projectorVersion, revision: source.revision, phase: source.phase, teams: source.teams.map((team) => ({ ...team, teamId: persistenceId(team.teamId), ...(team.captainUserId ? { captainUserId: persistenceId(team.captainUserId) } : {}), members: team.members.map((member) => ({ ...member, userId: persistenceId(member.userId), })), })), format: source.format, seriesGraph: source.seriesGraph, projection: source.projection, createdAt: new Date(source.createdAt), updatedAt: new Date(source.updatedAt), }; } function factForPersistence(fact: CompetitionMigrationFact): AnyDocument { const recordedAt = new Date(fact.recordedAt); const common: AnyDocument = { ...fact, _id: persistenceId(fact.id), competitionId: persistenceId(fact.competitionId), occurredAt: new Date(fact.occurredAt), recordedAt, createdAt: recordedAt, updatedAt: recordedAt, }; delete common.id; if (fact.type === 'game-accepted') { common.gameId = persistenceId(fact.gameId); common.seriesId = persistenceId(fact.seriesId); common.gameSlotId = persistenceId(fact.gameSlotId); common.mapping = { ...fact.mapping, blueTeamId: persistenceId(fact.mapping.blueTeamId), redTeamId: persistenceId(fact.mapping.redTeamId), winnerTeamId: persistenceId(fact.mapping.winnerTeamId), participantAssignments: fact.mapping.participantAssignments.map( (assignment) => ({ ...assignment, userId: persistenceId(assignment.userId), teamId: persistenceId(assignment.teamId), }), ), }; } else { common.seriesId = persistenceId(fact.seriesId); common.decision = 'winnerTeamId' in fact.decision ? { ...fact.decision, winnerTeamId: persistenceId(fact.decision.winnerTeamId), } : fact.decision; } return common; } function assignmentForPersistence( assignment: CompetitionMigrationAssignment, ): AnyDocument { const reservedAt = new Date(assignment.reservedAt); const updatedAt = new Date( assignment.releasedAt ?? assignment.usedAt ?? assignment.reservedAt, ); const voidedAt = assignment.state === 'voided' ? new Date( assignment.releasedAt ?? assignment.usedAt ?? assignment.reservedAt, ) : undefined; return { _id: persistenceId(assignment.id), competitionId: persistenceId(assignment.competitionId), seriesId: persistenceId(assignment.seriesId), gameSlotId: persistenceId(assignment.gameSlotId), tournamentCodeId: persistenceId(assignment.tournamentCodeId), state: assignment.state, reservedAt, ...(assignment.usedAt ? { usedAt: new Date(assignment.usedAt) } : {}), ...(assignment.releasedAt ? { releasedAt: new Date(assignment.releasedAt) } : {}), ...(voidedAt ? { voidedAt } : {}), ...(assignment.riotMatchId ? { riotMatchId: assignment.riotMatchId } : {}), commandId: assignment.commandId, createdAt: reservedAt, updatedAt, }; } function factForProjection( fact: Readonly>, ): Readonly> { const canonical = canonicalValue(fact) as Readonly>; return { ...canonical, id: idString(fact.id ?? fact._id) }; } function planResult( matchId: string, plan: ReturnType, ): CompetitionDomainMigrationMatchResult { if (plan.status === 'quarantined') { return { status: 'quarantined', matchId, warnings: plan.warnings, reasons: plan.reasons, }; } return { status: 'ready', matchId, competitionId: plan.competition.id, factCount: plan.facts.length, assignmentCount: plan.assignments.length, warnings: plan.warnings, }; } function failedResult( matchId: string, error: unknown, ): CompetitionDomainMigrationMatchResult { return { status: 'failed', matchId, warnings: [], error: error instanceof Error ? error.message : String(error), }; } function summarize( matches: CompetitionDomainMigrationMatchResult[], ): CompetitionDomainMigrationSummary { const count = (status: CompetitionDomainMigrationMatchResult['status']) => matches.filter((match) => match.status === status).length; return { scanned: matches.length, ready: count('ready'), applied: count('applied'), alreadyApplied: count('already-applied'), quarantined: count('quarantined'), failed: count('failed'), unclassified: count('failed'), factsPlanned: matches.reduce( (sum, match) => sum + ('factCount' in match ? match.factCount : 0), 0, ), assignmentsPlanned: matches.reduce( (sum, match) => sum + ('assignmentCount' in match ? match.assignmentCount : 0), 0, ), warnings: matches.reduce((sum, match) => sum + match.warnings.length, 0), }; } function assertExpectedCompetitionId( matchId: string, linkedCompetitionId: string, ): void { const expected = deterministicCompetitionId(matchId); if (linkedCompetitionId !== expected) { throw new Error( `Match ${matchId} links Competition ${linkedCompetitionId}; expected deterministic Competition ${expected}.`, ); } } function deterministicCompetitionId(matchId: string): string { return createHash('sha256') .update(JSON.stringify([matchId, 'competition'])) .digest('hex') .slice(0, 24); } function assertFieldsEqual( actual: Record, expected: Record, fields: string[], label: string, ): void { for (const field of fields) { if (canonicalJson(actual[field]) !== canonicalJson(expected[field])) { throw new Error(`${label} has conflicting persisted field ${field}.`); } } } function assertOptions(options: CompetitionDomainMigrationOptions): void { if ( options.limit !== undefined && (!Number.isInteger(options.limit) || options.limit < 1) ) { throw new Error('Competition migration limit must be a positive integer.'); } if (options.dryRun === false && !options.startSession) { throw new Error('Apply mode requires a transaction session factory.'); } if (options.afterMatchId !== undefined) { assertMatchCursor(options.afterMatchId); } } function assertMatchCursor(value: string): void { if (!/^[a-f\d]{24}$/i.test(value)) { throw new Error( 'Competition migration afterMatchId must be a 24-character hexadecimal Match ObjectId.', ); } } async function readCursor( cursor: CompetitionDomainMigrationCursor, ): Promise { const result: AnyDocument[] = []; for await (const document of cursor) result.push(document); return result; } function numberField(document: Record, field: string): number { const value = document[field]; if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) { throw new Error(`Competition has invalid ${field}.`); } return value; } function persistenceId(value: unknown): unknown { if (value instanceof mongoose.Types.ObjectId) return value; const stringValue = idString(value); return mongoose.Types.ObjectId.isValid(stringValue) && /^[a-f\d]{24}$/i.test(stringValue) ? new mongoose.Types.ObjectId(stringValue) : value; } function optionalIdString(value: unknown): string | undefined { return value === undefined || value === null || value === '' ? undefined : idString(value); } function idString(value: unknown): string { if (value instanceof mongoose.Types.ObjectId) return value.toHexString(); if (hasHexString(value)) { const rendered = value.toHexString(); if (typeof rendered === 'string') return rendered; } return String(value); } function arrayOf(value: unknown): unknown[] { return Array.isArray(value) ? value : []; } function uniqueStrings(values: unknown[]): string[] { return [ ...new Set( values.filter( (value): value is string => typeof value === 'string' && value.trim().length > 0, ), ), ].sort(); } function isRecord(value: unknown): value is Record { return value !== null && typeof value === 'object' && !Array.isArray(value); } function dateOrUndefined(value: unknown): Date | undefined { if (value === undefined || value === null || value === '') return undefined; const date = value instanceof Date ? value : new Date(value as string); return Number.isNaN(date.getTime()) ? undefined : date; } function canonicalHash(value: unknown): string { return `sha256:${createNodeHash(canonicalJson(value))}`; } function createNodeHash(value: string): string { // Kept in one helper so canonical hashes use exactly one encoding. return createHash('sha256').update(value).digest('hex'); } function canonicalJson(value: unknown): string { return JSON.stringify(canonicalValue(value)); } function canonicalValue(value: unknown): unknown { if (value instanceof mongoose.Types.ObjectId) return value.toHexString(); if (value instanceof Date) return value.toISOString(); if (hasHexString(value)) { const rendered = value.toHexString(); if (typeof rendered === 'string') return rendered; } if (Array.isArray(value)) return value.map(canonicalValue); if (isRecord(value)) { return Object.fromEntries( Object.entries(value) .filter(([, child]) => child !== undefined) .sort(([left], [right]) => left.localeCompare(right)) .map(([key, child]) => [key, canonicalValue(child)]), ); } return value; } function hasHexString(value: unknown): value is { toHexString(): unknown } { return ( value !== null && typeof value === 'object' && 'toHexString' in value && typeof value.toHexString === 'function' ); }