cito-mcp 0.4.0 → 0.4.2

package/dist/tools/normalize.js

@@ -62,6 +62,138 @@ 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;
+    let won = 0;
+    let parsed = 0;
+    for (const token of score.split(/[\s,]+/)) {
+        if (!token)
+            continue;
+        const set = parseTennisSetToken(token);
+        if (!set)
+            continue;
+        parsed += 1;
+        const mine = side === 1 ? set.p1 : set.p2;
+        const theirs = side === 1 ? set.p2 : set.p1;
+        if (mine > theirs)
+            won += 1;
+    }
+    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;
+    let won = 0;
+    let parsed = 0;
+    for (const raw of sets) {
+        const s = asRecord(raw);
+        if (!s)
+            continue;
+        const p1 = numOrNull(s.player1_games);
+        const p2 = numOrNull(s.player2_games);
+        if (p1 === null || p2 === null)
+            continue;
+        parsed += 1;
+        const mine = side === 1 ? p1 : p2;
+        const theirs = side === 1 ? p2 : p1;
+        if (mine > theirs)
+            won += 1;
+    }
+    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;
+    const p1 = numOrNull(sr.player1_games);
+    const p2 = numOrNull(sr.player2_games);
+    if (p1 === null || p2 === null)
+        return false;
+    const hi = Math.max(p1, p2);
+    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) {
+        let isWinner = opts.isWinner;
+        if (isWinner === null || isWinner === undefined) {
+            if (opts.winnerId && opts.sideId)
+                isWinner = opts.winnerId === opts.sideId;
+        }
+        if (isWinner === true)
+            return wsw;
+        if (isWinner === false)
+            return lsw;
+    }
+    const fromSets = tennisSetsWonFromSets(Array.isArray(opts.sets) ? opts.sets : [], opts.side);
+    if (fromSets !== null)
+        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
@@ -82,9 +214,11 @@ function imagesFrom(game, ...sources) {
         return null;
     };
     const images = {
-        headshotUrl: pick('headshotUrl', 'headshot'),
+        // 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'),
+        imageUrl: pick('imageUrl', 'image', 'photoUrl', 'logoUrl', 'logo', 'portrait_url'),
         proxiedImageUrl: pick('proxiedImageUrl', 'proxiedHeadshotUrl'),
     };
     if (!images.proxiedImageUrl) {
@@ -125,7 +259,9 @@ 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);
-    const country = pickString(o.country, profile?.country);
+    // `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);
     return {
@@ -238,11 +374,38 @@ export function normalizeMatch(game, row, forcedStatus) {
         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 score1 = typeof p1obj?.sets_won === 'number' ? p1obj.sets_won : undefined;
-            const score2 = typeof p2obj?.sets_won === 'number' ? p2obj.sets_won : undefined;
-            team1 = sideFrom(p1, pickString(p1obj?.id, r.player1_id), undefined, score1);
-            team2 = sideFrom(p2, pickString(p2obj?.id, r.player2_id), undefined, score2);
+            const p1Id = pickString(p1obj?.id, r.player1_id) ?? null;
+            const p2Id = pickString(p2obj?.id, r.player2_id) ?? null;
+            const winnerId = pickString(r.winner_id) ?? null;
+            const boolOrNull = (v) => (typeof v === 'boolean' ? v : null);
+            const score1 = tennisSetsWon({
+                sideSetsWon: p1obj?.sets_won,
+                winnerSetsWon: r.winner_sets_won,
+                loserSetsWon: r.loser_sets_won,
+                isWinner: boolOrNull(p1obj?.is_winner),
+                winnerId,
+                sideId: p1Id,
+                sets: r.sets,
+                score: scoreText,
+                side: 1,
+            });
+            const score2 = tennisSetsWon({
+                sideSetsWon: p2obj?.sets_won,
+                winnerSetsWon: r.winner_sets_won,
+                loserSetsWon: r.loser_sets_won,
+                isWinner: boolOrNull(p2obj?.is_winner),
+                winnerId,
+                sideId: p2Id,
+                sets: r.sets,
+                score: scoreText,
+                side: 2,
+            });
+            team1 = sideFrom(p1, p1Id ?? undefined, undefined, score1, sideExtras(p1obj ?? {}, game));
+            team2 = sideFrom(p2, p2Id ?? undefined, undefined, score2, sideExtras(p2obj ?? {}, game));
         }
         else {
             // Archive detail nests winner/loser objects with real names; list rows
@@ -254,8 +417,25 @@ 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) {
-                team1 = sideFrom(wName ?? wId, wId, undefined, undefined);
-                team2 = sideFrom(lName ?? lId, lId, undefined, undefined);
+                // 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,
+                    isWinner: true,
+                    sets: r.sets,
+                    score: scoreText,
+                    side: 1,
+                });
+                const lScore = tennisSetsWon({
+                    winnerSetsWon: r.winner_sets_won,
+                    loserSetsWon: r.loser_sets_won,
+                    isWinner: false,
+                    sets: r.sets,
+                    score: scoreText,
+                    side: 2,
+                });
+                team1 = sideFrom(wName ?? wId, wId, undefined, wScore);
+                team2 = sideFrom(lName ?? lId, lId, undefined, lScore);
             }
         }
     }
@@ -440,9 +620,21 @@ export function normalizeMatch(game, row, forcedStatus) {
         ? 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) &&
+        [eventName, eventSlug, r.tournament_name, r.tournament]
+            .filter((v) => typeof v === 'string' && v.length > 0)
+            .some((v) => v.trim().toLowerCase() === explicit.trim().toLowerCase());
     const weightOrClass = pickString(r.weightClass, r.division, r.weight_class, r.boutClass);
     let label;
-    if (explicit && !explicitIsPlaceholder) {
+    if (explicit && !explicitIsPlaceholder && !explicitIsEventName) {
         label = explicit;
     }
     else if (team1?.name || team2?.name) {
@@ -483,12 +675,19 @@ export function normalizeMatch(game, row, forcedStatus) {
     if (game === 'tennis' && Array.isArray(r.sets) && r.sets.length) {
         tennisSets = r.sets.map((s) => {
             const sr = asRecord(s) ?? {};
+            const p1g = numOrNull(sr.player1_games);
+            const p2g = numOrNull(sr.player2_games);
             return {
-                setNumber: numOrNull(sr.set_num),
-                player1Games: numOrNull(sr.player1_games),
-                player2Games: numOrNull(sr.player2_games),
+                // 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)),
-                completed: sr.is_completed === true,
+                // 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),
             };
         });
         tennisGameScore = pickString(r.game_score) ?? null;
@@ -624,7 +823,14 @@ export function rankScore(query, name, id, slug, ...extra) {
                 best = Math.max(best, 92); // "jon jones" vs "Jon Jones"
             }
             else {
-                const hits = qt.filter((t) => ct.some((x) => x.includes(t) || t.includes(x))).length;
+                // 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)

package/dist/tools/odds.js

@@ -53,6 +53,39 @@ function normalizeBookmaker(row) {
         markets,
     };
 }
+/**
+ * The one tennis-odds projection, shared by `tennis_odds` and `match_details`.
+ *
+ * Both surfaces read the same REST payload, and before this the two disagreed:
+ * `tennis_odds scope=match` served FanDuel 1.105 / Matchbook 1.13 with implied
+ * probabilities while `match_details sections:["odds"]` answered
+ * NOT_IMPLEMENTED "UFC only today" for the same match id. A caller could not
+ * tell whether tennis odds existed. One shaper, one answer.
+ */
+export function summarizeTennisOdds(data) {
+    const root = asRecord(data) ?? {};
+    // fetchJson hands back the whole REST envelope; the unit tests feed the inner
+    // object directly. Accept both.
+    const payload = asRecord(root.data) ?? root;
+    const coverage = asRecord(payload.coverage) ?? {};
+    const bookmakers = (Array.isArray(payload.bookmakers) ? payload.bookmakers : []).map(normalizeBookmaker);
+    const hasOdds = coverage.odds === true || bookmakers.length > 0;
+    return {
+        matchId: pickString(payload.match_id) ?? null,
+        oddsFormat: pickString(payload.odds_format) ?? 'decimal',
+        commenceTime: pickString(payload.commence_time) ?? null,
+        /** Upstream says the feed has since moved on; the prices are still real. */
+        stale: payload.stale === true,
+        bookmakers,
+        // Explicit, because an empty bookmakers[] is otherwise indistinguishable
+        // from a failed scrape.
+        oddsAvailable: hasOdds,
+        note: hasOdds
+            ? null
+            : 'No bookmaker is currently quoting this match. This is an upstream coverage gap, not an error; retry closer to the start time.',
+        fullBookPath: '/tennis/odds/{matchId}',
+    };
+}
 function parseTennis(args, tool) {
     const gameParse = parseGame(args.game, { allowAll: false, required: true });
     if (gameParse.error || !gameParse.game || !isPrimaryGame(gameParse.game)) {
@@ -92,6 +125,10 @@ Do not use when: the match result → match_details; rankings → standings.
 Tennis-only. Odds are decimal. Coverage is partial upstream: a match with no
 priced bookmaker returns coverage.odds=false and an empty bookmakers[] rather
 than invented numbers, and this tool surfaces that distinction explicitly.
+A match id that does not exist is a NOT_FOUND error, not a coverage gap: the
+odds route answers 200/odds:false for every unknown id, so scope=match and
+scope=live verify the match against /tennis/matches/{id} before reporting a gap,
+and set matchExists.
 
 Parallel-safe: yes. Upstream cost: 1.`,
     inputSchema: {
@@ -166,15 +203,35 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 const r = asRecord(row) ?? {};
                 const home = asRecord(r.home) ?? {};
                 const away = asRecord(r.away) ?? {};
+                const homeId = pickString(home.player_id, home.id) ?? null;
+                const awayId = pickString(away.player_id, away.id) ?? null;
+                const matchId = pickString(r.match_id, r.id) ?? null;
+                const oddsEventId = pickString(r.odds_event_id) ?? null;
                 return {
-                    matchId: pickString(r.match_id, r.id) ?? null,
-                    oddsEventId: pickString(r.odds_event_id) ?? null,
+                    matchId,
+                    oddsEventId,
                     tournament: pickString(r.tournament) ?? null,
                     commenceTime: pickString(r.commence_time, r.starts_at) ?? null,
-                    player1: { name: pickString(home.name) ?? null, id: pickString(home.player_id, home.id) ?? null },
-                    player2: { name: pickString(away.name) ?? null, id: pickString(away.player_id, away.id) ?? null },
+                    player1: { name: pickString(home.name) ?? null, id: homeId },
+                    player2: { name: pickString(away.name) ?? null, id: awayId },
                     bookmakers: Array.isArray(r.bookmakers) ? r.bookmakers.map((b) => pickString(b) ?? null) : [],
                     live: r.live === true,
+                    /**
+                     * The feed does not join its odds events to matches: every row of
+                     * /tennis/odds/upcoming carries match_id:null (verified on all 94
+                     * rows), so a caller could not go odds -> match and the two halves of
+                     * a betting UI could not be stitched together. matchId itself is left
+                     * exactly as the feed states it — null stays null, because inventing
+                     * one would be worse — and the join key that DOES resolve is named
+                     * alongside it.
+                     */
+                    joinKey: matchId
+                        ? { kind: 'matchId', matchId }
+                        : oddsEventId
+                            ? { kind: 'oddsEventId', oddsEventId }
+                            : null,
+                    /** Player ids present on the row, which identify the fixture when matchId is null. */
+                    playerIds: [homeId, awayId].filter((x) => Boolean(x)),
                 };
             });
             const total = typeof body.total === 'number' ? body.total : items.length;
@@ -206,6 +263,8 @@ Parallel-safe: yes. Upstream cost: 1.`,
             ? `/tennis/odds/${encodeURIComponent(matchId)}`
             : `/tennis/odds/${encodeURIComponent(matchId)}/live`;
         const res = await fetchJson(ctx, path, {});
+        let upstreamCalls = 1;
+        let rateLimit = res.headers;
         if (!res.ok) {
             return errorEnvelope({
                 code: mapHttpToCode(res.status, { gameNotIncluded: gameNotIncludedHint(res.data) }),
@@ -220,30 +279,73 @@ Parallel-safe: yes. Upstream cost: 1.`,
                 recover: ['Check the match id with live_matches or match_details'],
             });
         }
-        const root = asRecord(res.data) ?? {};
-        const body = asRecord(root.data) ?? root;
-        const coverage = asRecord(body.coverage) ?? {};
-        const bookmakers = (Array.isArray(body.bookmakers) ? body.bookmakers : []).map(normalizeBookmaker);
-        const hasOdds = coverage.odds === true || bookmakers.length > 0;
+        const summary = summarizeTennisOdds(res.data);
+        /**
+         * A match id that does not exist and a real match nobody is quoting look
+         * identical on the wire.
+         *
+         * /tennis/odds/{id} answers HTTP 200 with `coverage: { odds: false }` for
+         * EVERY id it does not know — verified for `s365_2026_0000000` (a plausible
+         * typo) and for the literal string `total-garbage-id`, both of which came
+         * back 200/odds:false. So the status code cannot tell them apart, and this
+         * tool used to report a typo as "upstream coverage gap, not an error" with
+         * ok:true — leaving the caller to conclude a real match has no prices.
+         *
+         * /tennis/matches/{id} DOES 404 for those same ids (verified: 404 NOT_FOUND
+         * for both, 200 for a real one), so that is the discriminator. It costs one
+         * extra call, and only on the no-odds path, where the answer is otherwise
+         * useless. player_stats already gets this right (404 -> NOT_FOUND); this
+         * makes odds agree with it.
+         */
+        let matchExists = null;
+        if (summary.oddsAvailable !== true) {
+            const probe = await fetchJson(ctx, `/tennis/matches/${encodeURIComponent(matchId)}`);
+            upstreamCalls += 1;
+            rateLimit = { ...rateLimit, ...probe.headers };
+            matchExists = probe.ok;
+            if (!matchExists) {
+                // Live ids live at /matches/live/{id} until the match archives.
+                const liveProbe = await fetchJson(ctx, `/tennis/matches/live/${encodeURIComponent(matchId)}`);
+                upstreamCalls += 1;
+                rateLimit = { ...rateLimit, ...liveProbe.headers };
+                matchExists = liveProbe.ok;
+            }
+            if (!matchExists) {
+                return errorEnvelope({
+                    code: 'NOT_FOUND',
+                    message: `No tennis match with id '${matchId}' — the odds feed has no event for it because the id itself does not exist`,
+                    game,
+                    source: 'tennis_odds',
+                    requestId,
+                    tookMs: Date.now() - started,
+                    upstreamCalls,
+                    rateLimit,
+                    httpStatus: 200,
+                    recover: [
+                        'Check the id with live_matches or tennis_schedule / match_summary',
+                        'Ids come from live_matches (s365_*) or the archive (s365_{year}_{gid})',
+                        `For the pre-match odds list instead, call tennis_odds { game: "tennis", scope: "upcoming" }`,
+                    ],
+                });
+            }
+        }
         return successEnvelope({
             source: 'tennis_odds',
             game,
             requestId,
             tookMs: Date.now() - started,
-            upstreamCalls: 1,
-            rateLimit: res.headers,
+            upstreamCalls,
+            rateLimit,
             data: {
                 title: `Tennis ${scopeRaw} odds — ${matchId}`,
                 scope: scopeRaw,
-                matchId: pickString(body.match_id) ?? matchId,
-                oddsFormat: pickString(body.odds_format) ?? 'decimal',
-                bookmakers,
-                // Explicit, because an empty bookmakers[] is otherwise indistinguishable
-                // from a failed scrape.
-                oddsAvailable: hasOdds,
-                note: hasOdds
-                    ? null
-                    : 'No bookmaker is currently quoting this match. This is an upstream coverage gap, not an error; retry closer to the start time.',
+                // One projection, the same object match_details sections:["odds"]
+                // returns. See summarizeTennisOdds.
+                ...summary,
+                matchId: summary.matchId ?? matchId,
+                // true when the no-odds path verified the match exists; null when odds
+                // existed so no verification was needed.
+                matchExists,
             },
         });
     },

package/dist/tools/player.js

@@ -53,9 +53,16 @@ function identityFrom(game, raw, idHint, slugHint) {
          * own domain, so it works from a browser without hotlink/CORS trouble.
          */
         images: {
-            headshotUrl: pickString(r.headshotUrl, r.headshot) ?? null,
+            // Tennis supplies exactly one likeness, `portrait_url` (a Wikimedia
+            // portrait), and no separate square headshot crop. Before this, the shaper
+            // read only headshotUrl/bodyImageUrl/imageUrl/photoUrl — none of which the
+            // tennis route emits — so every tennis profile shipped four explicit nulls
+            // while a perfectly good photo sat one key away, and builders concluded
+            // tennis had no images at all. The portrait fills the headshot slot too:
+            // a card with the real photo slightly cropped beats a faceless card.
+            headshotUrl: pickString(r.headshotUrl, r.headshot, r.portrait_url) ?? null,
             bodyImageUrl: pickString(r.bodyImageUrl, r.fullBodyImageUrl) ?? null,
-            imageUrl: pickString(r.imageUrl, r.image, r.photoUrl) ?? null,
+            imageUrl: pickString(r.imageUrl, r.image, r.photoUrl, r.portrait_url) ?? null,
             proxiedImageUrl: pickString(r.proxiedImageUrl, r.proxiedHeadshotUrl) ?? null,
         },
     };
@@ -1064,16 +1071,85 @@ Upstream cost: 1.`,
          * Map an arbitrary {label: value} breakdown without assuming the upstream
          * key set: the endpoint has grown keys before and a hardcoded list would
          * silently drop new ones.
+         *
+         * Values that are OBJECTS are skipped rather than coerced to null. That
+         * coercion is exactly what broke `bySurface`: the endpoint publishes
+         * `surface_breakdown: { hard: { matches, won, lost, win_pct, titles }, ... }`
+         * (one object per surface) and this ran each value through Number(), so
+         * every tennis player's surface split came back
+         * `{hard:null, clay:null, grass:null, carpet:null}` — permanently, on every
+         * profile, while `player_profile` served the identical numbers from the
+         * identical source. A key that is present and null reads as "this player
+         * has no clay record", which is a worse lie than omitting it.
+         */
+        const camel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+        const flatNumeric = (value) => {
+            const rec = asRecord(value);
+            if (!rec)
+                return null;
+            const out = {};
+            for (const [k, v] of Object.entries(rec)) {
+                if (asRecord(v))
+                    continue;
+                out[camel(k)] = num(v);
+            }
+            return Object.keys(out).length > 0 ? out : null;
+        };
+        /**
+         * One OBJECT per bucket (surface, level, …), with the bucket's own fields
+         * renamed to stable camelCase keys. A bucket that arrives as a bare number
+         * is preserved as { value }, so a shape change narrows the payload instead
+         * of emptying it.
          */
-        const numericBlock = (value) => {
+        const bucketBlock = (value, fields) => {
             const rec = asRecord(value);
             if (!rec)
                 return null;
             const out = {};
-            for (const [k, v] of Object.entries(rec))
-                out[k] = num(v);
+            for (const [bucket, raw] of Object.entries(rec)) {
+                const inner = asRecord(raw);
+                if (inner) {
+                    const mapped = {};
+                    for (const [outKey, srcKey] of fields) {
+                        if (srcKey in inner)
+                            mapped[outKey] = num(inner[srcKey]);
+                    }
+                    out[bucket] = Object.keys(mapped).length > 0 ? mapped : flatNumeric(inner) ?? {};
+                }
+                else {
+                    out[bucket] = { value: num(raw) };
+                }
+            }
             return Object.keys(out).length > 0 ? out : null;
         };
+        const SURFACE_FIELDS = [
+            ['matches', 'matches'],
+            ['won', 'won'],
+            ['lost', 'lost'],
+            ['winPct', 'win_pct'],
+            ['titles', 'titles'],
+        ];
+        const bySurface = bucketBlock(body.surface_breakdown ?? body.by_surface, SURFACE_FIELDS);
+        const byLevel = bucketBlock(body.by_level ?? body.level_breakdown, SURFACE_FIELDS);
+        const servingStats = flatNumeric(body.serving_stats);
+        const returnStats = flatNumeric(body.return_stats);
+        const clutchAndSituational = flatNumeric(body.clutch_and_situational);
+        const grandSlamBreakdown = bucketBlock(body.grand_slam_breakdown, SURFACE_FIELDS);
+        // Sections this endpoint declares but does not publish for this player.
+        // Named explicitly so an absent key is not read as "no such data exists".
+        const unavailable = {};
+        if (!byLevel) {
+            unavailable.byLevel =
+                'This endpoint publishes no per-level breakdown. Pass level= to a player_stats call, or use tournaments/event_card for level-scoped results.';
+        }
+        if (!returnStats)
+            unavailable.returnStats = 'Not published for this player yet.';
+        if (!clutchAndSituational) {
+            unavailable.clutchAndSituational = 'Not published for this player yet.';
+        }
+        if (!grandSlamBreakdown) {
+            unavailable.grandSlamBreakdown = 'Not published for this player yet.';
+        }
         return successEnvelope({
             source: 'player_stats',
             game,
@@ -1102,8 +1178,13 @@ Upstream cost: 1.`,
                     mastersTitles: num(summary.masters_titles),
                     finalsReached: num(summary.finals_reached),
                 },
-                bySurface: numericBlock(body.by_surface ?? body.surface_breakdown),
-                byLevel: numericBlock(body.by_level ?? body.level_breakdown),
+                bySurface,
+                byLevel,
+                servingStats,
+                returnStats,
+                clutchAndSituational,
+                grandSlamBreakdown,
+                ...(Object.keys(unavailable).length > 0 ? { unavailable } : {}),
             },
         });
     },