cito-mcp 0.4.4 → 0.4.6

package/dist/tools/normalize.js

@@ -1,19 +1,5 @@
-/**
- * Cross-game row normalization for live/schedule boards and entity cards.
- */
 import { asRecord, pickString, unwrapPayload, DEFAULT_API_BASE } from '../client.js';
 const IMAGE_PROXY_BASE = (process.env.CITO_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
-/**
- * Bout rows carry raw ufc.com URLs but no proxied variant (only the fighter
- * detail endpoint includes one). ufc.com can hotlink-block and sends no CORS
- * header, so a browser-side card built straight off those URLs shows broken
- * images. The proxy token is base64url of the source URL — verified to
- * round-trip and serve HTTP 200 — so derive it rather than making the caller
- * N+1 the fighter endpoint just to get a loadable image.
- *
- * UFC only: /public/images/lol/<token> returns HTTP 400, so other games get
- * their raw URL and a null proxy rather than a fabricated link.
- */
 function deriveProxiedImageUrl(rawUrl, game) {
     if (!rawUrl || game !== 'ufc')
         return null;
@@ -28,14 +14,6 @@ function deriveProxiedImageUrl(rawUrl, game) {
         return null;
     return `${IMAGE_PROXY_BASE}/public/images/ufc/${Buffer.from(rawUrl, 'utf8').toString('base64url')}`;
 }
-/**
- * Tennis has players, not teams. The cross-game NormalizedMatch type keeps
- * team1/team2 internally for every game so the rest of this module stays
- * uniform (nestedSide, sidesMatch, sortByCardOrder, …); this renames those two
- * keys — and, when present, a nested score sub-object shaped the same way —
- * at the JSON boundary for tennis only. Every other game passes through
- * unchanged.
- */
 export function presentSides(obj, game) {
     if (game !== 'tennis' || !obj || typeof obj !== 'object')
         return obj;
@@ -62,28 +40,12 @@ function numOrNull(v) {
         return Number(v);
     return null;
 }
-/**
- * One set of a tennis score string ("6-4", "7-6(6)", "6-4, 3-6") as games won.
- *
- * A tiebreak is parenthesised after the games ("7-6(6)"), so the regex stops at
- * the games. Anything else returns null rather than a guess: retirement rows
- * carry "6-3 2-1 RET", and reading "RET" as games would invent a set.
- */
 export function parseTennisSetToken(token) {
     const m = /^\s*(\d{1,2})\s*-\s*(\d{1,2})/.exec(token);
     if (!m)
         return null;
     return { p1: Number(m[1]), p2: Number(m[2]) };
 }
-/**
- * Sets won by one side, counted from the match-level game score
- * ("4-6 6-3 6-3 7-5" → 3 for side 1, 1 for side 2).
- *
- * `score` orders every token as player1-player2 on this feed, which is verified
- * against the same row's sets[] (set 1: score token "4-6", player1_games 4,
- * player2_games 6). Ties are impossible in a completed set, so a token where
- * neither side is ahead contributes to neither total.
- */
 export function tennisSetsWonFromScore(score, side) {
     if (!score)
         return null;
@@ -103,15 +65,6 @@ export function tennisSetsWonFromScore(score, side) {
     }
     return parsed > 0 ? won : null;
 }
-/**
- * Sets won by one side, counted from the structured sets[] array.
- *
- * player1_games/player2_games are the ONLY side-correct pair here. The sibling
- * winner_games/loser_games are oriented to the match winner, not to side 1 —
- * on s365_2026_4849786 set 1 is `winner_games: 4, loser_games: 6` while side 1
- * (the winner, Shelton) actually lost that set 4-6. Reading those would have
- * produced a confidently wrong 1-3 scoreline.
- */
 export function tennisSetsWonFromSets(sets, side) {
     if (!Array.isArray(sets) || sets.length === 0)
         return null;
@@ -133,14 +86,6 @@ export function tennisSetsWonFromSets(sets, side) {
     }
     return parsed > 0 ? won : null;
 }
-/**
- * Whether a set row is finished.
- *
- * The live route states `is_completed`; the archive route omits the key
- * entirely, and reading only the flag marked all four sets of a COMPLETED US
- * Open semi-final `completed: false`. When the flag is absent the games decide:
- * a set is over at 6-x with a two-game margin, or at 7-6/7-5.
- */
 export function tennisSetCompleted(sr) {
     if (typeof sr.is_completed === 'boolean')
         return sr.is_completed;
@@ -152,30 +97,10 @@ export function tennisSetCompleted(sr) {
     const lo = Math.min(p1, p2);
     return (hi >= 6 && hi - lo >= 2) || (hi === 7 && lo === 6);
 }
-/**
- * Sets won by one side of a tennis match, from whichever spelling the row uses.
- *
- * Four sources exist because three different endpoints describe the same match:
- *   1. `sets_won`            — the live route puts it on each player object
- *   2. `winner_sets_won`/`loser_sets_won` — the archive route's own totals
- *   3. `sets[]`              — per-set games, present on both
- *   4. the `score` string    — "4-6 6-3 6-3 7-5", present on both
- *
- * The archive route (`/tennis/matches/{id}`) carries NO sets_won on its player
- * objects at all, which is why a completed US Open semi-final rendered as
- * "Ben Shelton - : - Frances Tiafoe" while the same response held the real
- * score in `score` and in `sets[]`. Reading only source 1 is the bug; the order
- * above is authority, not preference — a server-computed total beats a count we
- * derive, and the structured array beats re-parsing a display string.
- */
 export function tennisSetsWon(opts) {
     const explicit = numOrNull(opts.sideSetsWon);
     if (explicit !== null)
         return explicit;
-    // winner_sets_won / loser_sets_won belong to a side, and which side is known
-    // either from the row's own is_winner flag or by matching ids. Without one of
-    // those signals the pair is unusable and the structured sets below are safer
-    // than a coin flip.
     const wsw = numOrNull(opts.winnerSetsWon);
     const lsw = numOrNull(opts.loserSetsWon);
     if (wsw !== null && lsw !== null) {
@@ -194,12 +119,6 @@ export function tennisSetsWon(opts) {
         return fromSets;
     return tennisSetsWonFromScore(opts.score ?? undefined, opts.side);
 }
-/**
- * Collect image URLs from a corner/team row and its nested profile. Returns
- * undefined when the upstream carried none, so lean rows stay lean; when any
- * image exists every key is present (null where absent) — a missing key would
- * read as "this API has no images" rather than "no image for this one".
- */
 function imagesFrom(game, ...sources) {
     const pick = (...keys) => {
         for (const src of sources) {
@@ -214,15 +133,12 @@ function imagesFrom(game, ...sources) {
         return null;
     };
     const images = {
-        // portrait_url is the tennis feed's only likeness (see identityFrom in
-        // player.ts); without it a tennis side on every board carried no image.
         headshotUrl: pick('headshotUrl', 'headshot', 'portrait_url'),
         bodyImageUrl: pick('bodyImageUrl', 'fullBodyImageUrl'),
         imageUrl: pick('imageUrl', 'image', 'photoUrl', 'logoUrl', 'logo', 'portrait_url'),
         proxiedImageUrl: pick('proxiedImageUrl', 'proxiedHeadshotUrl'),
     };
     if (!images.proxiedImageUrl) {
-        // Prefer the headshot for the proxied variant — it is the crop a card UI wants.
         images.proxiedImageUrl =
             deriveProxiedImageUrl(images.headshotUrl, game) ??
                 deriveProxiedImageUrl(images.imageUrl, game);
@@ -249,7 +165,6 @@ function recordFrom(...sources) {
     }
     return undefined;
 }
-/** Enrichment shared by UFC corners and (where upstream supplies it) team rows. */
 function sideExtras(o, game) {
     const profile = asRecord(o.profile) ?? undefined;
     const fighter = asRecord(o.fighter) ?? undefined;
@@ -259,8 +174,6 @@ function sideExtras(o, game) {
     const rank = pickString(o.rankText, o.rank, profile?.rankText);
     const championStatus = pickString(o.championStatus, profile?.championStatus);
     const division = pickString(profile?.division, o.division, o.weightClass);
-    // `ioc` is the tennis feed's country code ("ESP"); it was not read, so every
-    // tennis side on every board came back country-less.
     const country = pickString(o.country, profile?.country, o.ioc);
     const flag = pickString(o.flag, profile?.flag);
     const outcome = pickString(o.outcome);
@@ -269,12 +182,7 @@ function sideExtras(o, game) {
         ...(images ? { images } : {}),
         ...(record ? { record } : {}),
         ...(rank ? { rank } : {}),
-        // "none" carries no signal for a page; only surface an actual belt state.
         ...(championStatus && championStatus.toLowerCase() !== 'none' ? { championStatus } : {}),
-        // UFC corners always carry these keys. A debutant with no ranked division
-        // was shipping with the key ABSENT while every other corner had it, and a
-        // fighter from a country with no flag mapping did the same, which breaks
-        // strict parsers. Null says "not known"; absence says nothing.
         ...(game === 'ufc'
             ? { division: division ?? null, country: country ?? null, flag: flag ?? null }
             : {
@@ -311,12 +219,6 @@ function scoreNum(v) {
         return Number(v);
     return null;
 }
-/**
- * Collapse the six spellings one outcome arrives in ("SUB" / "Submission",
- * "U-DEC" / "Decision - Unanimous", "KO/TKO" / "TKO") onto one enum. The raw
- * string is kept alongside as methodRaw; this is a stable key for consumers,
- * not a rewrite of the source.
- */
 export function normalizeUfcMethod(raw) {
     if (!raw)
         return undefined;
@@ -346,15 +248,12 @@ export function normalizeUfcMethod(raw) {
     return raw.trim();
 }
 export function normalizeMatch(game, row, forcedStatus) {
-    // Always peel { success, data } so UFC bout fighters[] / status are visible.
     const r = asRecord(unwrapPayload(row)) ?? asRecord(row) ?? {};
-    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.fightMetricId, r.ufcFightId, r.live_match_id) ?? 'unknown';
+    const matchId = pickString(r.matchId, r.boutId, r.id, r.gameId, r.match_id, r.dataId, r.live_match_id) ?? 'unknown';
     let team1 = nestedSide(r.team1, game) ??
         sideFrom(pickString(r.team1Name, r.team_a_name, r.redName, r.fighter1Name, r.homeName), pickString(r.team1Id, r.team1_id, r.redId, r.fighter1Id), pickString(r.team1Slug, r.redSlug, r.fighter1Slug), scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore));
     let team2 = nestedSide(r.team2, game) ??
         sideFrom(pickString(r.team2Name, r.team_b_name, r.blueName, r.fighter2Name, r.awayName), pickString(r.team2Id, r.team2_id, r.blueId, r.fighter2Id), pickString(r.team2Slug, r.blueSlug, r.fighter2Slug), scoreNum(r.team2Score ?? r.score2 ?? r.team2Maps ?? r.blueScore));
-    // CS2 rows nest team1/team2 objects that lack a score; a nested side must not
-    // shadow the flat score fields (team1Score/score1/team1Maps) with score:null.
     if (team1 && team1.score == null) {
         const s = scoreNum(r.team1Score ?? r.score1 ?? r.team1Maps ?? r.redScore);
         if (s != null)
@@ -365,17 +264,11 @@ export function normalizeMatch(game, row, forcedStatus) {
         if (s != null)
             team2 = { ...team2, score: s };
     }
-    // Tennis: the live board nests player1/player2 objects ({id,name,sets_won});
-    // raw live rows carry player1_name/player2_name; archive rows only carry
-    // winner_id/loser_id (ids, no names). Map all three onto sides so labels are
-    // never "? vs ?" and live scores surface as sets won.
     if (game === 'tennis' && !team1 && !team2) {
         const p1obj = asRecord(r.player1);
         const p2obj = asRecord(r.player2);
         const p1 = pickString(p1obj?.name, r.player1_name);
         const p2 = pickString(p2obj?.name, r.player2_name);
-        // winner_sets_won/loser_sets_won and score/sets are match-level; only the
-        // side flags differ, so they are shared by both branches below.
         const scoreText = pickString(r.score, r.score_raw) ?? null;
         if (p1 || p2) {
             const p1Id = pickString(p1obj?.id, r.player1_id) ?? null;
@@ -408,8 +301,6 @@ export function normalizeMatch(game, row, forcedStatus) {
             team2 = sideFrom(p2, p2Id ?? undefined, undefined, score2, sideExtras(p2obj ?? {}, game));
         }
         else {
-            // Archive detail nests winner/loser objects with real names; list rows
-            // may only carry winner_id/loser_id (ids double as last-resort labels).
             const wObj = asRecord(r.winner);
             const lObj = asRecord(r.loser);
             const wName = pickString(wObj?.name, r.winner_name);
@@ -417,7 +308,6 @@ export function normalizeMatch(game, row, forcedStatus) {
             const wId = pickString(wObj?.id, r.winner_id);
             const lId = pickString(lObj?.id, r.loser_id);
             if (wName || lName || wId || lId) {
-                // This shape IS winner-first, so side 1 is the winner by construction.
                 const wScore = tennisSetsWon({
                     winnerSetsWon: r.winner_sets_won,
                     loserSetsWon: r.loser_sets_won,
@@ -439,9 +329,6 @@ export function normalizeMatch(game, row, forcedStatus) {
             }
         }
     }
-    // UFC / live corners: red/blue objects, corner arrays, or fighters[] with corner field.
-    // Public API serializeBout uses fighters:[{ corner, fighterName, fighterSlug, profile:{name,slug} }].
-    // Live tracking uses red/blue + fighters[] (not team1/team2).
     if (game === 'ufc' || (!team1 && !team2 && (r.red || r.blue || Array.isArray(r.fighters)))) {
         const fromCornerObj = (raw) => {
             const o = asRecord(raw);
@@ -450,14 +337,9 @@ export function normalizeMatch(game, row, forcedStatus) {
                     return { name: raw.trim() };
                 return null;
             }
-            // Nested profile from serializeBoutFighter
             const profile = asRecord(o.profile);
             const fighter = asRecord(o.fighter);
             const name = pickString(o.name, o.fighterName, o.displayName, o.nickname, profile?.name, profile?.nickname, fighter?.name, fighter?.nickname);
-            // o.id on a serialized corner is the ufc_bout_fighters ROW id, unique per
-            // bout, so the same human got a different "id" on every card. Prefer the
-            // fighter's own id wherever the API supplies it; fall back to the row id
-            // only when nothing better exists.
             const id = pickString(o.fighterId, profile?.id, fighter?.id, o.id);
             const slug = pickString(o.slug, o.fighterSlug, profile?.slug, fighter?.slug);
             const score = scoreNum(o.score ?? o.points);
@@ -479,7 +361,7 @@ export function normalizeMatch(game, row, forcedStatus) {
         if (fightersList.length) {
             const byCorner = (want) => fightersList.find((f) => {
                 const c = pickString(asRecord(f)?.corner, asRecord(f)?.side)?.toLowerCase();
-                return c === want || c === want[0]; // "red" / "r"
+                return c === want || c === want[0];
             });
             const redF = byCorner('red') ?? byCorner('r') ?? fightersList[0];
             const blueF = byCorner('blue') ??
@@ -489,13 +371,6 @@ export function normalizeMatch(game, row, forcedStatus) {
             team2 = team2 ?? fromCornerObj(blueF);
         }
     }
-    // UFC fighter-history rows (/ufc/fighters/{slug}/fights). These carry the
-    // fighter as fighterSlug/fighterName, the other corner under opponent, and
-    // the result as outcome, with NO fighters[] and no team1/team2. Every reader
-    // was left with two null sides: head_to_head filtered on those nulls and
-    // reported Jones vs Cormier as never having met, the profile showed
-    // team1:null with the division as the label, and the preview form could not
-    // say who won. One shape, three symptoms.
     if (game === 'ufc' && !team1 && !team2 && typeof r.fighterSlug === 'string') {
         const opp = asRecord(r.opponent);
         const selfCorner = pickString(r.corner)?.toLowerCase();
@@ -503,8 +378,6 @@ export function normalizeMatch(game, row, forcedStatus) {
         const other = opp
             ? sideFrom(pickString(opp.name) ?? pickString(opp.slug), undefined, pickString(opp.slug), undefined, sideExtras(opp, game))
             : null;
-        // Keep red on team1 when we know the corner, so a card and a history row
-        // agree on which side is which.
         if (selfCorner === 'blue' && other) {
             team1 = other;
             team2 = self;
@@ -514,19 +387,11 @@ export function normalizeMatch(game, row, forcedStatus) {
             team2 = other;
         }
     }
-    // COD sometimes uses teams[]
     if ((!team1 || !team2) && Array.isArray(r.teams)) {
         team1 = team1 ?? nestedSide(r.teams[0], game);
         team2 = team2 ?? nestedSide(r.teams[1], game);
     }
-    const startTime = pickString(r.startTime, r.scheduledAt, 
-    // Tennis emits scheduled_at; startTime was the API's only camelCase key
-    // and was removed. Without this the upcoming board loses its clock.
-    r.scheduled_at, 
-    // A live row reports when it went in-play, not when it was scheduled.
-    r.started_at, r.startsAt, r.date, r.startDate, r.beginAt, asRecord(r.event)?.startsAt, asRecord(r.event)?.startTime, asRecord(r.event)?.date) ?? null;
-    // Tennis archive rows carry the state as outcome (COMPLETED / RETIREMENT /
-    // WALKOVER); read it, or every finished match reported status unknown.
+    const startTime = pickString(r.startTime, r.scheduledAt, r.scheduled_at, r.started_at, r.startsAt, r.date, r.startDate, r.beginAt, asRecord(r.event)?.startsAt, asRecord(r.event)?.startTime, asRecord(r.event)?.date) ?? null;
     const statusRaw = pickString(r.status, r.state, r.matchStatus, r.boutStatus, r.outcome)?.toLowerCase() ?? '';
     let status = forcedStatus ?? 'unknown';
     if (!forcedStatus) {
@@ -534,16 +399,11 @@ export function normalizeMatch(game, row, forcedStatus) {
             r.resultRound != null ||
             r.isComplete === true ||
             r.completed === true;
-        // "started" as a bare substring also matches "not_started", which is how a
-        // fixture that has not begun was being served to customers as live. Require
-        // word boundaries, refuse the explicit not-started spellings, and refuse any
-        // match whose kickoff is still in the future: a scheduled match cannot be
-        // in progress no matter what the upstream status string says.
         const unstarted = /not[_\s-]?started|unstarted|not[_\s-]?begun|yet[_\s-]?to[_\s-]?start/.test(statusRaw);
         const looksLive = !unstarted && /\b(live|running|in[_\s-]?progress|ongoing|started|watching)\b/.test(statusRaw);
         const kickoffPassed = (() => {
             if (!startTime)
-                return true; // no clock to contradict the feed
+                return true;
             const t = Date.parse(startTime);
             return !Number.isFinite(t) || t <= Date.now();
         })();
@@ -556,7 +416,6 @@ export function normalizeMatch(game, row, forcedStatus) {
         }
         else if (/upcoming|scheduled|not_?started|unstarted|pending|soon|booked|confirmed|announced|tbd/.test(statusRaw) ||
             (game === 'ufc' && !hasResult && (startTime || statusRaw === '' || statusRaw === 'unknown'))) {
-            // UFC bouts often omit status or use sparse values; default upcoming when no result yet.
             if (hasResult)
                 status = 'completed';
             else if (startTime) {
@@ -570,20 +429,12 @@ export function normalizeMatch(game, row, forcedStatus) {
         else if (hasResult)
             status = 'completed';
     }
-    // The winner, resolved once. Explicit winner fields first; otherwise a
-    // history row states the result from the fighter's own side (outcome: win /
-    // loss), which translates back into a slug. Both the score below and the
-    // result block use this, so a fight the profile shows as a win also counts
-    // as a win in head_to_head's tally, which reads the scores.
     const historyOutcome = pickString(r.outcome)?.toLowerCase();
     const historyOpponent = pickString(asRecord(r.opponent)?.slug);
-    const resolvedWinnerSlug = 
-    // winner_id is the tennis archive's spelling; winner there is an object.
-    pickString(r.winnerFighterSlug, r.winnerSlug, r.winner, r.winner_id) ??
+    const resolvedWinnerSlug = pickString(r.winnerFighterSlug, r.winnerSlug, r.winner, r.winner_id) ??
         (historyOutcome === 'win' && typeof r.fighterSlug === 'string' ? r.fighterSlug
             : historyOutcome === 'loss' && historyOpponent ? historyOpponent
                 : undefined);
-    // Winner → score 1-0 for UFC card display when numeric scores absent
     if (game === 'ufc' && team1 && team2 && team1.score == null && team2.score == null) {
         const winner = resolvedWinnerSlug?.toLowerCase();
         if (winner) {
@@ -606,26 +457,13 @@ export function normalizeMatch(game, row, forcedStatus) {
     const leagueName = pickString(asRecord(r.league)?.name, r.leagueName, r.league, r.leagueSlug);
     const leagueId = pickString(asRecord(r.league)?.id, r.leagueId);
     const leagueSlug = pickString(asRecord(r.league)?.slug, r.leagueSlug);
-    // Prefer explicit title/label when present, but never keep the placeholder
-    // "? vs ?" once fighter/team names were resolved (UFC fighters[] / red-blue).
-    // When both sides lack names, prefer event / weight / bout id over opaque "? vs ?"
-    // so agent boards (live_matches, upcoming_schedule, event_card) stay legible.
     const vsLabel = `${team1?.name ?? '?'} vs ${team2?.name ?? '?'}`;
     const explicitRaw = pickString(r.label, r.title, r.name);
-    // UFC history rows put the division where a title would go ("Heavyweight"),
-    // which then displaced "Jon Jones vs Stipe Miocic" as the label. A label that
-    // merely repeats the weight class is not a matchup; use the sides instead.
     const explicit = game === 'ufc' && explicitRaw && (team1?.name || team2?.name) &&
         explicitRaw.toLowerCase() === (pickString(r.weightClass, r.division) ?? '').toLowerCase()
         ? undefined
         : explicitRaw;
     const explicitIsPlaceholder = explicit != null && /^\?\s*vs\s*\?$/i.test(explicit.trim());
-    // Tennis rows carry no `label`, but the live route does set `name` — and that
-    // name is the TOURNAMENT ("Challenger, Seville"), not the matchup. Preferring
-    // it made live_matches label a tennis row by its event while
-    // upcoming_schedule, off a route with no such field, labelled the same
-    // fixture "Max Alcala Gurri vs Dusan Lajovic". Two boards, one match, two
-    // labels. A "matchup" that is really an event name is not a matchup.
     const explicitIsEventName = explicit != null &&
         game === 'tennis' &&
         Boolean(team1?.name || team2?.name) &&
@@ -641,14 +479,11 @@ export function normalizeMatch(game, row, forcedStatus) {
         label = vsLabel;
     }
     else {
-        // Identity fallbacks — never invent fighter names, but avoid bare "? vs ?"
         label =
             pickString(eventName, eventSlug, weightOrClass) ??
                 (matchId && matchId !== 'unknown' ? `Bout ${matchId}` : null) ??
                 vsLabel;
     }
-    // Bout metadata already present on the upstream row. Passing it through here
-    // is what stops an agent from N+1'ing call_api to rebuild a fight card.
     const cardSection = pickString(r.cardSection, r.cardSegment, r.segment);
     const cardPosition = pickString(r.cardPosition);
     const cardSectionOrder = numOrNull(r.cardSectionOrder);
@@ -658,16 +493,11 @@ export function normalizeMatch(game, row, forcedStatus) {
     const method = normalizeUfcMethod(methodRaw);
     const methodDetails = pickString(r.methodDetails);
     const resultTime = pickString(r.resultTime);
-    // UFC sends referee as { id, name, firstName, lastName } — not a string.
     const referee = pickString(r.referee, asRecord(r.referee)?.name);
     const winnerSlug = resolvedWinnerSlug;
     const resultRound = numOrNull(r.resultRound);
     const hasResultDetail = method != null || resultRound != null || winnerSlug != null || resultTime != null;
     const isCancelled = r.isCancelled === true;
-    // Tennis live/detail rows carry a top-level sets[] (set_num/player*_games/
-    // tiebreak/is_completed) plus game_score/server/current_set. A live board
-    // that only reports "score: 1" cannot tell 6-0 6-0 from a 7-6 in progress;
-    // carry the real breakdown through instead of collapsing it to an integer.
     let tennisSets;
     let tennisGameScore = null;
     let tennisServer = null;
@@ -678,15 +508,11 @@ export function normalizeMatch(game, row, forcedStatus) {
             const p1g = numOrNull(sr.player1_games);
             const p2g = numOrNull(sr.player2_games);
             return {
-                // The live route spells it set_num; the archive route set_number. Both
-                // are emitted by the same API for the same set.
                 setNumber: numOrNull(sr.set_num) ?? numOrNull(sr.set_number),
                 score: pickString(sr.score) ?? (p1g !== null && p2g !== null ? `${p1g}-${p2g}` : null),
                 player1Games: p1g,
                 player2Games: p2g,
                 tiebreak: sr.tiebreak == null ? null : (pickString(sr.tiebreak) ?? String(sr.tiebreak)),
-                // is_completed is a live-route field only; the archive route omits it
-                // and every set of a finished match read as completed:false.
                 completed: tennisSetCompleted(sr),
             };
         });
@@ -704,8 +530,6 @@ export function normalizeMatch(game, row, forcedStatus) {
         team2,
         event: eventName || eventId || eventSlug ? { id: eventId, slug: eventSlug, name: eventName } : null,
         league: leagueName || leagueId || leagueSlug ? { id: leagueId, slug: leagueSlug, name: leagueName } : null,
-        // weightClass is UFC vocabulary; other games never set it, but never lie
-        // it into existence from a tennis/LoL row that merely shares a field name.
         ...(weightOrClass && game === 'ufc' ? { weightClass: weightOrClass } : {}),
         ...(r.titleBout != null ? { titleBout: Boolean(r.titleBout) } : {}),
         ...(hasCard
@@ -721,10 +545,6 @@ export function normalizeMatch(game, row, forcedStatus) {
         ...(hasResultDetail
             ? {
                 result: {
-                    // method/referee are combat-sport vocabulary with no tennis
-                    // meaning; a tennis history row otherwise picks up a
-                    // result.method:null / result.referee:null pair from this same
-                    // object shape, which reads as "render a fight" to an agent.
                     ...(game === 'ufc' ? { method: method ?? null, referee: referee ?? null } : {}),
                     methodRaw: methodRaw ?? null,
                     methodDetails: methodDetails ?? null,
@@ -742,11 +562,6 @@ export function normalizeMatch(game, row, forcedStatus) {
             : {}),
     };
 }
-/**
- * Sort a fight card the way it is presented: main card before prelims, and the
- * main event at the top of its section. Rows without placement keep their
- * upstream order behind those that have it.
- */
 export function sortByCardOrder(rows) {
     const rank = (x, i) => ({
         section: x.card?.sectionOrder ?? Number.MAX_SAFE_INTEGER,
@@ -768,7 +583,6 @@ export function entityRef(row, type, game) {
         pickString(r.slug) ??
         'unknown';
     const slug = pickString(r.slug, r.orgSlug, r.teamSlug);
-    // Events often use `title` not `name` (UFC)
     const name = pickString(r.name, r.full_name, r.player_name, r.title, r.nickname, r.displayName, r.tag, r.code, slug, id) ?? id;
     const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname);
     return {
@@ -789,11 +603,6 @@ export function entityRef(row, type, game) {
         },
     };
 }
-/**
- * Fuzzy score for entity resolution: exact > startsWith > includes > token overlap.
- * Extra args (nickname, alt names) are scored as additional candidates.
- * Multi-token person names ("jon jones") get a strong boost when every token hits.
- */
 export function rankScore(query, name, id, slug, ...extra) {
     const q = query.trim().toLowerCase().replace(/\s+/g, ' ');
     if (!q)
@@ -816,27 +625,18 @@ export function rankScore(query, name, id, slug, ...extra) {
             best = Math.max(best, 55 - Math.min(20, c.indexOf(q)));
         else {
             const ct = c.split(/[\s]+/).filter(Boolean);
-            // all query tokens present as whole tokens (order-independent)
             const allTokens = qt.length > 0 &&
                 qt.every((t) => ct.some((x) => x === t || x.startsWith(t) || t.startsWith(x)));
             if (allTokens && qt.length >= 2) {
-                best = Math.max(best, 92); // "jon jones" vs "Jon Jones"
+                best = Math.max(best, 92);
             }
             else {
-                // A hit is the candidate token containing the query token, or the query
-                // token containing a candidate token OF REAL LENGTH. The reverse
-                // direction used to accept any length, so the single letter "e" in
-                // "E Skinner" counted as a hit against the query "sinner" ("sinner"
-                // contains "e") and scored 32 — which is how eight strangers padded a
-                // search for one player. A one- or two-character fragment carries no
-                // identity, so it no longer counts.
                 const hits = qt.filter((t) => ct.some((x) => x.includes(t) || (t.includes(x) && x.length >= 3))).length;
                 if (hits === qt.length && qt.length > 0)
                     best = Math.max(best, 75);
                 else if (hits)
                     best = Math.max(best, 20 + hits * 12);
             }
-            // last-name only: query last token equals candidate last token
             if (qt.length >= 2 && ct.length >= 1 && ct[ct.length - 1] === qt[qt.length - 1]) {
                 best = Math.max(best, 60);
             }
@@ -844,13 +644,6 @@ export function rankScore(query, name, id, slug, ...extra) {
     }
     return best;
 }
-/**
- * Edition year encoded in a tennis-style entity id ("atp_2026_580" -> 2026).
- *
- * `/tennis/competitions` returns no `year` field while the calendar does, so
- * the id is the only signal available on both, and the two tools that disagreed
- * about "Australian Open" were each reading a different one of those endpoints.
- */
 export function editionYear(id, explicit) {
     const direct = Number(explicit);
     if (Number.isFinite(direct) && direct > 1800)
@@ -858,22 +651,6 @@ export function editionYear(id, explicit) {
     const match = /^[a-z]+_(\d{4})_/i.exec(String(id ?? ''));
     return match ? Number(match[1]) : null;
 }
-/**
- * Deterministic winner among rows whose names match a query equally well.
- *
- * "Australian Open" is two rows in every season, one ATP and one WTA, sharing a
- * name exactly. resolve_entity read /tennis/competitions, which lists ATP
- * first; event_card read /tennis/tournaments/calendar, which lists WTA first;
- * and neither applied a tiebreak, so the same question got atp_2026_580 from
- * one tool and wta_2026_580 from the other. Neither answer was wrong on its
- * own. The absence of a rule was the bug.
- *
- * Order: an exact name beats a substring, a newer edition beats an older one,
- * and the id settles whatever is left. That last step is arbitrary, and that is
- * fine -- it only has to be FIXED, which is the property that was missing.
- * Callers that need the alternatives still surface them; this only decides
- * which single row is called "best".
- */
 export function chooseNamedEntity(rows, needle, read) {
     const want = needle.trim().toLowerCase();
     if (!want || !rows.length)