cito-mcp 0.4.3 → 0.4.5

package/dist/tools/insight.js

@@ -1,6 +1,3 @@
-/**
- * match_preview — pre-match briefing composite
- */
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, unwrapPayload, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { chooseNamedEntity, normalizeMatch, presentSides, sortByCardOrder } from './normalize.js';
@@ -14,8 +11,6 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
     let recentForm = [];
     let keyPlayers = [];
     if (game === 'tennis') {
-        // Profile + match log. Without this branch the preview fell to the generic
-        // fallback and presented player ids where names belong.
         const res = await fetchJson(ctx, `/tennis/players/${encodeURIComponent(side)}`);
         calls += 1;
         rateLimit = res.headers;
@@ -66,7 +61,6 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
             entity = {
                 id: pickString(data.id, data.slug, side),
                 slug: pickString(data.slug, side),
-                // Prefer real display name; never leave entity.name as the slug when name exists
                 name: pickString(data.name, data.displayName, data.nickname, side) ?? side,
                 nickname: pickString(data.nickname) ?? null,
                 division: pickString(data.division) ?? null,
@@ -81,7 +75,6 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
                 httpStatus: res.status,
             }));
         }
-        // Fight-by-fight form (not aggregate stats alone)
         const fights = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(side)}/fights`, {
             query: { limit: recentLimit },
         });
@@ -91,11 +84,6 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
             recentForm = extractRows(unwrapPayload(fights.data) ?? fights.data)
                 .slice(0, recentLimit)
                 .map((row) => {
-                // History rows nest the bout and carry the fighter's own side as
-                // fighterSlug/opponent/outcome. Merge so normalizeMatch sees both,
-                // and do NOT force 'completed': the fighter's next scheduled bout is
-                // in this list too, and stamping it completed put an unfought fight
-                // at the top of the form with no result.
                 const r = asRecord(row) ?? {};
                 const bout = asRecord(r.bout) ?? {};
                 return normalizeMatch('ufc', { ...bout, ...r });
@@ -105,11 +93,10 @@ async function loadSide(ctx, game, side, recentLimit, includeRosters) {
         calls += 1;
         rateLimit = { ...rateLimit, ...stats.headers };
         if (stats.ok && recentForm.length === 0) {
-            recentForm = []; // keep empty rather than stuffing aggregate as "matches"
+            recentForm = [];
             keyPlayers = [];
         }
         if (stats.ok) {
-            // stash aggregate on entity for talking points
             entity = { ...entity, stats: unwrapPayload(stats.data) };
         }
         return { entity, roster, recentForm, keyPlayers, calls, partial, rateLimit };
@@ -254,9 +241,6 @@ export function composeH2H(game, sideA, sideB, rows, limit) {
     const bl = sideB.toLowerCase();
     const meetings = rows
         .map((row) => normalizeMatch(game, row))
-        // A meeting is a fight that happened. The upcoming bout between the two
-        // sides sits in the same history list and must not count as a prior
-        // meeting, or every preview reports the fight it is previewing as H2H.
         .filter((m) => m.status === 'completed')
         .filter((m) => {
         const s1 = [m.team1?.id, m.team1?.slug, m.team1?.name].filter(Boolean).map((x) => String(x).toLowerCase());
@@ -270,8 +254,6 @@ export function composeH2H(game, sideA, sideB, rows, limit) {
         .slice(0, limit);
     return {
         meetings: meetings.length,
-        // Tennis has players, not teams: rename team1/team2 -> player1/player2 on
-        // the way out. Every other game keeps team1/team2 unchanged.
         lastMeetings: meetings.slice(0, 5).map((m) => presentSides(m, game)),
         recordNote: meetings.length ? `${meetings.length} past meetings found in window` : 'No past H2H meetings in window',
     };
@@ -331,10 +313,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
         const includeH2H = args.includeH2H !== false;
         const includeRosters = args.includeRosters !== false;
         const recentLimit = clampInt(args.recentLimit, 5, 1, 15);
-        // Optional tennis H2H surface filter (TENNIS-04 follow-through: the
-        // /tennis/h2h endpoint accepts surface=Hard|Clay|Grass). Canonicalise
-        // case so 'clay'/'CLAY' still hit; anything else is a validation error
-        // rather than a silently ignored filter.
         const surfaceRaw = typeof args.surface === 'string' ? args.surface.trim() : '';
         let surface;
         if (surfaceRaw) {
@@ -390,7 +368,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
             rateLimit = res.headers;
             if (res.ok) {
                 const entity = unwrapPayload(res.data);
-                // Do not force "upcoming" — completed bouts (e.g. UFC 300) should keep completed.
                 const m = normalizeMatch(game, entity);
                 context = {
                     matchId: m.matchId !== 'unknown' ? m.matchId : matchId,
@@ -401,14 +378,10 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     status: m.status,
                     label: m.label,
                 };
-                // Prefer stable slugs for follow-up fighter fetches
                 if (!teamA)
                     teamA = m.team1?.slug || m.team1?.id || m.team1?.name || '';
                 if (!teamB)
                     teamB = m.team2?.slug || m.team2?.id || m.team2?.name || '';
-                // Tennis archive detail carries winner/loser objects; if normalisation
-                // did not surface them as sides, read the ids straight off the record
-                // rather than failing the whole preview.
                 if (game === 'tennis') {
                     const rec = asRecord(entity) ?? {};
                     const w = asRecord(rec.winner) ?? asRecord(rec.player1) ?? {};
@@ -488,9 +461,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                         rows = extractRows(res.data);
                 }
                 else if (game === 'tennis') {
-                    // Tennis has a first-class H2H endpoint with the full rivalry; use it
-                    // rather than composing from a short form window, which reported
-                    // Sinner vs Alcaraz as never having met.
                     const h2hQuery = { player1_id: teamA, player2_id: teamB };
                     if (game === 'tennis' && surface)
                         h2hQuery.surface = surface;
@@ -499,9 +469,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     rateLimit = { ...rateLimit, ...h2hRes.headers };
                     if (h2hRes.ok) {
                         const rec = asRecord(unwrapPayload(h2hRes.data)) ?? {};
-                        // The payload names both players once at the top; rows name only
-                        // the winner. Resolve the loser's name from the top-level blocks
-                        // so a meeting reads "Sinner vs Alcaraz", not "Sinner vs atp_207989".
                         const p1 = asRecord(rec.player1) ?? {};
                         const p2 = asRecord(rec.player2) ?? {};
                         const nameOf = {
@@ -530,7 +497,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     }
                 }
                 else if (game === 'ufc') {
-                    // Fighter fight history is the H2H source of truth (not global /bouts page 1).
                     const hist = await fetchJson(ctx, `/ufc/fighters/${encodeURIComponent(teamA)}/fights`, {
                         query: { limit: 50 },
                     });
@@ -538,8 +504,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                     rateLimit = { ...rateLimit, ...hist.headers };
                     if (hist.ok) {
                         rows = extractRows(unwrapPayload(hist.data) ?? hist.data).map((row) => {
-                            // Keep fighterSlug/opponent/outcome alongside the bout; they are
-                            // the only place the two corners exist on a history row.
                             const r = asRecord(row) ?? {};
                             return { ...(asRecord(r.bout) ?? {}), ...r };
                         });
@@ -561,11 +525,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                 }));
             }
         }
-        // Factual briefing lines only — never structural meta like "roster loaded".
-        // Called with teamA + teamB and no matchId, context stayed empty
-        // ({ matchId:null, event:null, startTime:null }) for a headliner whose
-        // own form list had all three. Side A's history carries the booked bout
-        // against side B; that IS the context.
         if (!matchId && context.matchId == null) {
             const bl = String(teamB ?? '').toLowerCase();
             const booked = sideARes.recentForm.find((m) => {
@@ -649,9 +608,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
                 context,
                 sideA: {
                     entity: sideARes.entity,
-                    // A tennis player has no roster; the key never applied here, not
-                    // merely came back empty. UFC fighters get the same treatment
-                    // elsewhere in this surface — omit rather than ship a foreign key.
                     ...(game === 'tennis' ? {} : { roster: sideARes.roster }),
                     recentForm: sideARes.recentForm.map((m) => presentSides(m, game)),
                     keyPlayers: sideARes.keyPlayers,
@@ -668,9 +624,6 @@ Example: { "game": "lol", "teamA": "t1", "teamB": "gen-g", "includeH2H": true, "
         });
     },
 };
-/**
- * Resolve event id/slug from a free-text query via game event list.
- */
 async function resolveEventKey(ctx, game, q) {
     let calls = 0;
     let rateLimit = {};
@@ -678,11 +631,6 @@ async function resolveEventKey(ctx, game, q) {
     if (!needle)
         return { key: null, name: null, calls, rateLimit };
     if (game === 'tennis') {
-        // No free-text search on tournaments upstream; the season calendar is the
-        // complete list and is small enough to match locally.
-        // This year's calendar first, then the two before it: the archive lags
-        // the live season, so the current edition of an event may not exist yet
-        // (no 2026 Wimbledon row while 2025 does).
         const thisYear = new Date().getUTCFullYear();
         let hit;
         for (const year of [thisYear, thisYear - 1, thisYear - 2]) {
@@ -690,11 +638,6 @@ async function resolveEventKey(ctx, game, q) {
             calls += 1;
             rateLimit = res.headers;
             const rows = extractRows(unwrapPayload(res.data) ?? res.data).map((r) => asRecord(r) ?? {});
-            // .find() returned whatever the calendar happened to list first, and the
-            // calendar lists the WTA row before the ATP one for a shared name, while
-            // /tennis/competitions (which resolve_entity reads) lists them the other
-            // way round. Same query, two tools, two ids. One shared rule now settles
-            // both; see chooseNamedEntity.
             hit =
                 chooseNamedEntity(rows, needle, (r) => ({
                     id: pickString(r.id, r.tournament_id) ?? '',
@@ -776,7 +719,7 @@ Each bout carries weightClass, titleBout, card placement, and (once fought) resu
 { method, round, time, referee, winnerSlug }. Each corner carries images
 { headshotUrl, bodyImageUrl, imageUrl, proxiedImageUrl }, record, nickname, rank,
 championStatus, country and flag when upstream supplies them. Use proxiedImageUrl in
-browsers — ufc.com sends no CORS header. You do not need call_api per fighter for faces.
+browsers — the image host sends no CORS header. You do not need call_api per fighter for faces.
 
 Prefer over: agent-side resolve + call_api /ufc/events + bout expansion; N+1 match_summary for the card list only; per-fighter call_api just to fetch headshots.
 
@@ -794,16 +737,11 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
         type: 'object',
         additionalProperties: false,
         required: ['game'],
-        // The handler needs an event to look up, so `game` alone always fails.
-        // Say so in the schema rather than letting a client believe game suffices.
         anyOf: [{ required: ['eventIdOrSlug'] }, { required: ['q'] }],
         properties: {
             game: gameSchema({ allowAll: false, required: true }),
             eventIdOrSlug: stringSchema('Event or tournament id/slug. Prefer over q when known. Required unless q is given. Example: "ufc-300".', 'ufc-300'),
             q: stringSchema('Free-text event name when id/slug unknown. Example: "UFC 300". Resolves within this tool — still prefer resolve_entity when disambiguating many hits.', 'UFC 300'),
-            // Named for the general case (a card, a bracket, a match list), not
-            // combat-sport vocabulary — "bout" has no meaning for a tennis draw or a
-            // CS2 event hub, and this same parameter gates both.
             includeMatches: boolSchema('Include the bout/match list, or the tennis draw bracket (default true).', true),
             includeStandings: boolSchema('Include standings/rankings snippet when API supports event/tournament/division scope (default false). ' +
                 'For UFC this also joins divisional rank and movement onto each bout corner as team.rank / team.rankMovement — ' +
@@ -882,17 +820,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 });
             }
         }
-        /**
-         * Seeded with the key but explicitly NOT resolved.
-         *
-         * `name: q || eventKey` used to put the raw requested id in the name slot,
-         * and the tennis branch then kept it whenever its detail fetch failed
-         * (`pickString(d.name) ?? event.name`). event_card { eventIdOrSlug:
-         * "atp_2026_999999" } therefore answered ok:true with
-         * event.name = "atp_2026_999999" — an id presented as a tournament name,
-         * over a 404 that the partial[] block reported correctly. A name is
-         * something the API supplied or it is null; an identifier is not a name.
-         */
         let event = {
             id: eventKey,
             slug: eventKey,
@@ -902,20 +829,8 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
         };
         let bouts = [];
         let standingsSnippet = null;
-        // Tennis only: the draw bracket grouped by round, each round carrying the
-        // upstream's own round code (Q1..R128, QF, SF, F) so an agent can render
-        // the tournament tree rather than one flat, order-dependent match list.
         let drawRounds = null;
-        /**
-         * Draw completeness. A bracket is only useful if the caller knows whether it
-         * is whole: atp_2026_560 returns R32 15/16, R64 31/32 and R128 45/64 (the
-         * archived matches it actually holds), and the Final round is absent until
-         * it is played. The old response gave no signal at all, so a partial
-         * bracket silently looked like a complete one and a missing round looked
-         * like a missing feature.
-         */
         let drawSummary = null;
-        /** Matches a round of this code must contain, or null when unrecognised. */
         const expectedMatchesForRound = (code, drawSize) => {
             const c = (code ?? '').toUpperCase();
             const rMatch = /^R(\d+)$/.exec(c);
@@ -928,7 +843,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
             if (c === 'QF')
                 return 4;
             if (c === 'BR' || c === 'RR')
-                return null; // round robin has no fixed size
+                return null;
             if (drawSize && drawSize > 0 && c.startsWith('Q'))
                 return null;
             return null;
@@ -953,8 +868,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 if (includeBouts) {
                     const embedded = extractRows(inner.bouts ?? inner.fights ?? data.bouts);
                     if (embedded.length) {
-                        // Order the full card before slicing — truncating upstream order
-                        // first can drop the main event and keep an early prelim.
                         bouts = sortByCardOrder(embedded.map((row) => normalizeMatch('ufc', {
                             ...(asRecord(row) ?? {}),
                             eventName: event.name,
@@ -1014,9 +927,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     }));
                 }
             }
-            // Bout rows carry no start time of their own; inherit the card's. Without
-            // this the same bout said startTime:null here and the event time on
-            // upcoming_schedule, and a caller had to fetch both to learn when it is.
             const cardStart = typeof event.date === 'string' ? event.date : null;
             bouts = bouts.map((b) => ({ ...b, startTime: b.startTime ?? cardStart }));
             if (includeStandings) {
@@ -1024,10 +934,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 upstreamCalls += 1;
                 rateLimit = { ...rateLimit, ...ranks.headers };
                 if (ranks.ok) {
-                    // Bout rows carry rankText: null, so a card built from them alone is
-                    // rank-blind. The rankings payload is one row per fighter keyed by
-                    // slug, so join it onto the corners we already have instead of
-                    // handing back a raw blob the caller has to re-index itself.
                     const rankRows = extractRows(ranks.data)
                         .map((row) => asRecord(row))
                         .filter((r) => Boolean(r));
@@ -1052,14 +958,9 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                         };
                     };
                     bouts = bouts.map((b) => ({ ...b, team1: withRank(b.team1), team2: withRank(b.team2) }));
-                    // Scope the table to divisions actually on this card. The full ladder
-                    // is 176 rows (~42KB) and doubles the response; a card with no
-                    // bantamweight bout has no use for the bantamweight ladder, and that
-                    // context is not free for the agent reading it.
                     const cardDivisions = new Set(bouts
                         .flatMap((b) => [b.weightClass, b.team1?.division, b.team2?.division])
                         .filter((d) => Boolean(d))
-                        // "Welterweight Title" must still match the Welterweight ladder.
                         .map((d) => d.toLowerCase().replace(/\s+title$/, '').trim()));
                     const inScope = (r) => {
                         if (cardDivisions.size === 0)
@@ -1074,8 +975,7 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                         scope: 'division',
                         note: 'UFC global rankings (not an event bracket), joined onto bout corners as team.rank / team.rankMovement. ' +
                             (scoped.length > 0 && scoped.length < rankRows.length
-                                ? // Count the ladders actually returned, not the card's weight
-                                    // classes — catchweight bouts have no ranking ladder.
+                                ?
                                     `Rows filtered to the ${shownDivisions.length} ranked division(s) on this card; ${rankRows.length} rows exist across all divisions.`
                                 : 'All divisions shown.'),
                         divisions: shownDivisions,
@@ -1308,9 +1208,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
             }
         }
         else if (game === 'tennis') {
-            // Tournament detail plus the bracket. The draw is only populated once a
-            // tournament has results, so an event still in the future comes back
-            // with the detail and an empty bouts list, and says so.
             const detail = await fetchJson(ctx, `/tennis/tournaments/${encodeURIComponent(eventKey)}`);
             upstreamCalls += 1;
             rateLimit = { ...rateLimit, ...detail.headers };
@@ -1320,9 +1217,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     ...event,
                     id: pickString(d.id) ?? eventKey,
                     slug: pickString(d.id) ?? eventKey,
-                    // Never fall back to event.name here: that is the requested key, and
-                    // this branch only runs when the detail fetch SUCCEEDED, so the name
-                    // comes from the payload or it is honestly absent.
                     name: pickString(d.name, d.id) ?? null,
                     resolved: true,
                     tour: pickString(d.tour) ?? null,
@@ -1352,9 +1246,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     const rawRounds = Array.isArray(dd.rounds) ? dd.rounds : [];
                     const drawSize = typeof dd.draw_size === 'number' ? dd.draw_size : null;
                     const flat = [];
-                    // Fill the bracket from the front (the upstream orders rounds from the
-                    // business end backwards: SF, QF, R16, … R128), so a cap keeps the
-                    // decisive rounds and drops the early ones rather than the reverse.
                     let budget = drawMaxMatches ?? Number.POSITIVE_INFINITY;
                     let omittedMatches = 0;
                     drawRounds = rawRounds.map((rr) => {
@@ -1369,10 +1260,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                             const mr = asRecord(mm) ?? {};
                             const row = { ...mr, id: mr.match_id, round: roundName, tournament_name: event.name, status: 'completed' };
                             flat.push(row);
-                            // normalizeMatch gives named, id'd sides (player1/player2 once
-                            // presented); the raw score string and bracket-progression
-                            // fields are the only place the actual set score and next slot
-                            // live, so carry them alongside rather than dropping them.
                             return presentSides({
                                 ...normalizeMatch('tennis', row),
                                 score: pickString(mr.score) ?? null,
@@ -1400,17 +1287,12 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                     const shortRounds = drawRounds
                         .filter((r) => r.complete === false)
                         .map((r) => `${r.roundCode ?? r.roundName ?? '?'} ${r.returned}/${r.expected}`);
-                    // A round of 128 draw must have a Final. Its absence is not an error
-                    // (the final may simply not be played yet) but it IS the difference
-                    // between "in progress" and "the API lost a round".
                     const haveCodes = new Set(drawRounds.map((r) => (r.roundCode ?? '').toUpperCase()));
                     const missingRounds = ['F', 'SF', 'QF']
                         .filter((c) => !haveCodes.has(c))
                         .filter((c) => !(c === 'F' && shortRounds.length > 0 && drawSize !== null && returnedTotal < drawSize / 2));
                     drawSummary = {
                         drawSize,
-                        // NOT `rounds`: that key holds the round ARRAY on the same object,
-                        // and spreading a count over it replaced the bracket with a number.
                         roundCount: drawRounds.length,
                         matchesReturned: returnedTotal,
                         matchesExpected: expectedTotal || null,
@@ -1441,7 +1323,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
             }
         }
         else {
-            // dota2 — thin: tournament list + recent matches only
             warnings.push('Dota2 event_card is thin; expect partial bouts/standings');
             const detail = await fetchJson(ctx, `/dota2/tournaments/${encodeURIComponent(eventKey)}`);
             upstreamCalls += 1;
@@ -1497,15 +1378,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 }));
             }
         }
-        /**
-         * Last line of defence against an identifier posing as a name.
-         *
-         * Every game branch seeds `event.name` from `q`/`eventKey` so a partially
-         * resolved card still has something in the slot. Any branch that failed and
-         * left that seed in place would publish "atp_2026_999999" as a tournament
-         * name, and nothing downstream can tell an id from a name. It is nulled
-         * here; `resolved` records that the detail fetch never succeeded.
-         */
         if (event.resolved !== true && typeof event.name === 'string' && event.name === eventKey) {
             event = { ...event, name: null, nameResolved: false };
         }
@@ -1529,10 +1401,6 @@ Example: { "game": "ufc", "eventIdOrSlug": "ufc-300", "includeMatches": true, "i
                 event,
                 bouts: includeBouts ? bouts.map((b) => presentSides(b, game)) : [],
                 boutCount: includeBouts ? bouts.length : 0,
-                // Tennis only: the same matches grouped by round, with round codes
-                // (Q1..R128, QF, SF, F) and each match's score/bracket progression —
-                // this is what makes a bracket renderable; `bouts` above is the flat
-                // list every other game already gets.
                 ...(game === 'tennis' ? { draw: drawRounds ? { rounds: drawRounds, ...(drawSummary ?? {}) } : null } : {}),
                 standings: includeStandings ? standingsSnippet : null,
                 nextSteps: [

package/dist/tools/leaderboard.js

@@ -1,12 +1,3 @@
-/**
- * leaderboard_aces (TENNIS-18 follow-up).
- *
- * Tennis-only: season aces leaderboard from real match_stats aggregates
- * (GET /tennis/leaderboards/aces). Upstream shape (verified 2026-09-09):
- * { season, tour, stat: 'aces', items: [{ player_id, full_name, aces, matches }], total }.
- * Upstream defaults: season=2026, tour=null (both tours combined), and it
- * 422s on a bad tour or a non-year season — both surface as VALIDATION here.
- */
 import { asRecord, clampInt, fetchJson, gameNotIncludedHint, pickString, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
@@ -156,16 +147,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
         const root = asRecord(res.data);
         const body = asRecord(root?.data) ?? root ?? {};
         const items = (Array.isArray(body.items) ? body.items : []).map(normalizeAceRow);
-        /**
-         * `total` is the QUALIFYING POPULATION, not the page.
-         *
-         * The API used to return len(items) AFTER applying .limit(limit), so limit=2
-         * answered total:2 for a board with thousands of eligible players and the
-         * caller had no way to tell a page from the whole board. It now carries
-         * count(*) OVER (), the count of players passing the board's own threshold.
-         * `returned` and `hasMore` are stated separately so the two can never be
-         * confused again, and the threshold is surfaced so the number is explicable.
-         */
         const total = typeof body.total === 'number' ? body.total : items.length;
         return successEnvelope({
             pagination: {
@@ -318,8 +299,6 @@ Parallel-safe: yes. Upstream cost: 1.`,
             const root = asRecord(res.data);
             const body = asRecord(root?.data) ?? root ?? {};
             const items = (Array.isArray(body.items) ? body.items : []).map(normalizeRow);
-            // Same contract as leaderboard_aces: total is the qualifying population,
-            // not the page. See the note there.
             const total = typeof body.total === 'number' ? body.total : items.length;
             return successEnvelope({
                 pagination: {