cito-mcp 0.4.3 → 0.4.5

package/dist/tools/resolve.js

@@ -1,41 +1,14 @@
-/**
- * resolve_entity + search_entities
- */
 import { clampInt, decodeCursor, encodeCursor, extractRows, fetchJson, gameNotIncludedHint, pickString, asRecord, } from '../client.js';
 import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT, errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { editionYear, entityRef, rankScore } from './normalize.js';
 import { boolSchema, gameSchema, isPrimaryGame, limitSchema, parseGame, PRIMARY_GAMES, stringSchema, } from './types.js';
-/**
- * Minimum relevance a search result must reach to be returned when a query was
- * given. rankScore returns 0 for "no part of the query appears anywhere in this
- * row", so 1 means "must have matched something". See the floor note in
- * searchEntities for the live evidence.
- */
 export const RELEVANCE_FLOOR = 1;
-/**
- * Ranking order whose tiebreak never depends on the order upstream happened to
- * return rows in.
- *
- * "Australian Open" is two rows with byte-identical names and identical fuzzy
- * scores, one ATP and one WTA. The old comparator ran out of criteria there and
- * left the winner to the source ordering, and event_card reads a different
- * source that orders them the other way round, so the two tools answered the
- * same question with different ids. Newest edition, then id, matching
- * chooseNamedEntity so both paths land on the same row.
- */
 function byRank(a, b) {
     return (b.score - a.score
         || a.name.localeCompare(b.name)
         || ((editionYear(b.id) ?? -1) - (editionYear(a.id) ?? -1))
         || a.id.localeCompare(b.id));
 }
-/**
- * Query aliases for orgs whose common name is not their slug. Kept deliberately
- * small and one-directional: these map what a person types onto the canonical
- * slug, and are only used to grant an exact-match boost, never to rewrite a
- * result. SK Telecom T1 became T1 in 2019; sk-telecom-t1-k and -s remain
- * separate historical rosters and are NOT folded in.
- */
 const normalizeQueryKey = (v) => String(v || '').toLowerCase().replace(/[^a-z0-9]/g, '');
 const ORG_ALIASES = {
     skt: 't1',
@@ -44,8 +17,6 @@ const ORG_ALIASES = {
     skt1: 't1',
 };
 function pushCandidates(out, game, type, rows, q, limit) {
-    // Position within the upstream's own result list. That ordering is a real
-    // signal we otherwise throw away.
     let index = -1;
     for (const row of rows) {
         index += 1;
@@ -53,29 +24,10 @@ function pushCandidates(out, game, type, rows, q, limit) {
         const r = asRecord(row) ?? {};
         const nickname = pickString(r.nickname, asRecord(r.profile)?.nickname, ref.meta?.nickname);
         let score = rankScore(q, ref.name, ref.id, ref.slug, nickname);
-        // Ranked-player tiebreaker: a surname query like "Alcaraz" fuzzy-ties the
-        // world #2 with a 1991 journeyman; the row's current_rank breaks the tie
-        // toward whoever is actually active/ranked (tennis search supplies it).
         const currentRank = Number(r.current_rank);
         if (score > 0 && Number.isFinite(currentRank) && currentRank > 0) {
             score += currentRank <= 100 ? 8 : currentRank <= 1000 ? 4 : 2;
         }
-        /**
-         * The upstream's FIRST row is allowed to match on something we cannot see.
-         *
-         * /tennis/players/search is a dedicated name search and it knows nicknames
-         * and aliases that the payload does not carry: `q=Nole` returns Novak
-         * Djokovic first, and nothing in the string "Novak Djokovic" resembles
-         * "nole", so rankScore scores it 0. The old code floored every unmatched row
-         * to 1 and then sorted, which let a mere substring collision win —
-         * `resolve_entity { q: "Nole" }` answered **M Canoles** (a WTA player whose
-         * name contains "noles") and search_entities dropped Djokovic entirely.
-         *
-         * So when our own scorer finds no name match at all but the dedicated search
-         * put the row first, the row is kept as the alias answer and labelled. Only
-         * the first row, and only when our scorer is silent, so this can never
-         * outrank a query that genuinely matches a name.
-         */
         let matchedBy;
         if (q && score <= 0 && index === 0) {
             score = 95;
@@ -105,7 +57,6 @@ function pushCandidates(out, game, type, rows, q, limit) {
     if (out.length > limit * 3)
         out.length = limit * 3;
 }
-/** Drop noise tokens so "UFC Fight Night Medic" can match "UFC Fight Night: Medic vs Rodriguez". */
 function ufcSearchQueries(q) {
     const raw = q.trim();
     if (!raw)
@@ -118,20 +69,16 @@ function ufcSearchQueries(q) {
         .split(/\s+/)
         .filter((t) => t.length >= 3 && !stop.has(t));
     if (tokens.length) {
-        // distinctive tokens alone (e.g. "medic", "rodriguez")
         for (const t of tokens.slice(0, 4))
             queries.push(t);
-        // pair of last two distinctive tokens
         if (tokens.length >= 2)
             queries.push(tokens.slice(-2).join(' '));
     }
-    // slug-ish form
     const slugish = raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
     if (slugish && slugish !== raw.toLowerCase())
         queries.push(slugish);
     return [...new Set(queries.map((s) => s.trim()).filter(Boolean))];
 }
-/** UFC dedicated search (list /fighters ignores `q`). Multi-query for event fuzzy match. */
 async function ufcSearch(ctx, q, type, limit) {
     const candidates = [];
     let calls = 0;
@@ -158,7 +105,6 @@ async function ufcSearch(ctx, q, type, limit) {
         const bouts = Array.isArray(payload.bouts)
             ? payload.bouts
             : extractRows(payload.bouts);
-        // Always score against the *original* user query for ranking quality
         if (wantFighters)
             pushCandidates(candidates, 'ufc', 'fighter', fighters, q, limit);
         if (wantEvents)
@@ -166,7 +112,6 @@ async function ufcSearch(ctx, q, type, limit) {
         if (wantMatches)
             pushCandidates(candidates, 'ufc', 'match', bouts, q, limit);
     }
-    // Event soft-miss fallback: scan upcoming + recent event lists client-side
     if (wantEvents && !candidates.some((c) => c.type === 'event' && c.score >= 40)) {
         for (const path of ['/ufc/events/upcoming', '/ufc/events/recent', '/ufc/events']) {
             const res = await fetchJson(ctx, path, { query: { limit: 40, page: 1 } });
@@ -177,7 +122,6 @@ async function ufcSearch(ctx, q, type, limit) {
             pushCandidates(candidates, 'ufc', 'event', extractRows(res.data), q, limit);
         }
     }
-    // Dedupe by type+id
     const seen = new Set();
     const deduped = [];
     for (const c of candidates.sort(byRank)) {
@@ -212,7 +156,6 @@ async function searchGame(ctx, game, q, type, limit) {
                     }),
                 };
             }
-            // Unwrap the { success, data, meta } envelope before reading buckets.
             const envelope = asRecord(res.data) ?? {};
             const data = asRecord(envelope.data) ?? envelope;
             const buckets = [
@@ -231,7 +174,6 @@ async function searchGame(ctx, game, q, type, limit) {
             if (candidates.length === 0) {
                 const fallbackType = type === 'any' ? 'unknown' : type;
                 let rows = extractRows(data);
-                // extractRows prefers the `matches` bucket; never mislabel those rows as a non-match type.
                 if (fallbackType !== 'match' && fallbackType !== 'unknown') {
                     const matchRows = extractRows(data.matches);
                     if (matchRows.length && rows[0] === matchRows[0])
@@ -254,7 +196,6 @@ async function searchGame(ctx, game, q, type, limit) {
                     }),
                 };
             }
-            // Unwrap the { success, data, meta } envelope before reading buckets.
             const envelope = asRecord(res.data) ?? {};
             const data = asRecord(envelope.data) ?? envelope;
             for (const [t, key] of [
@@ -270,7 +211,6 @@ async function searchGame(ctx, game, q, type, limit) {
             if (candidates.length === 0) {
                 const fallbackType = type === 'any' ? 'unknown' : type;
                 let rows = extractRows(data);
-                // extractRows prefers the `matches` bucket; never mislabel those rows as a non-match type.
                 if (fallbackType !== 'match' && fallbackType !== 'unknown') {
                     const matchRows = extractRows(data.matches);
                     if (matchRows.length && rows[0] === matchRows[0])
@@ -299,7 +239,6 @@ async function searchGame(ctx, game, q, type, limit) {
             pushCandidates(candidates, game, type === 'any' ? 'unknown' : type, extractRows(res.data), q, limit);
         }
         else if (game === 'tennis') {
-            // Tennis has no combined /search; players and competitions are separate lookups.
             const tasks = [];
             if (type === 'any' || type === 'player') {
                 tasks.push((async () => {
@@ -329,19 +268,11 @@ async function searchGame(ctx, game, q, type, limit) {
             const tasks = [];
             if (type === 'any' || type === 'team') {
                 tasks.push((async () => {
-                    // Over-fetch before ranking. The upstream returns search hits in
-                    // alphabetical order, so asking for `limit` rows put the exact
-                    // match outside the window: "T1" returned mt1-esports, mt1-vision
-                    // and two SK Telecom rosters while the real t1 sat sixth and was
-                    // never seen. Rank a wide window, then cut.
                     const wide = String(Math.max(50, limit * 5));
                     const res = await fetchJson(ctx, '/lol/teams', { query: { search: q, limit: wide } });
                     calls += 1;
                     if (res.ok)
                         pushCandidates(candidates, game, 'team', extractRows(res.data), q, limit);
-                    // An alias is a name the API does not know. "SKT" returns no t1 row
-                    // at all, so ranking cannot help; search the canonical slug too and
-                    // score those rows against the canonical name.
                     const aliasTarget = ORG_ALIASES[normalizeQueryKey(q)];
                     if (aliasTarget) {
                         const alt = await fetchJson(ctx, '/lol/teams', { query: { search: aliasTarget, limit: wide } });
@@ -390,7 +321,6 @@ async function searchGame(ctx, game, q, type, limit) {
             await Promise.all(tasks);
         }
         else if (game === 'ufc') {
-            // /ufc/fighters ignores q (returns p4p/champ list). Always use /ufc/search when querying.
             if (q) {
                 const ufc = await ufcSearch(ctx, q, type, limit);
                 calls += ufc.calls;
@@ -523,11 +453,6 @@ Example: { "q": "T1", "game": "lol", "type": "team", "limit": 5 }`,
         all.sort(byRank);
         const candidates = all.slice(0, limit);
         const best = candidates[0] ?? null;
-        // An exact identity hit is not ambiguous, whatever else scored near it.
-        // "T1" ties with t1-rookies and t1-challengers on fuzzy score, which left
-        // the caller with needsDisambiguation and no decision to act on even though
-        // one candidate matched the query exactly. Aliases count: "SKT" resolves
-        // through ORG_ALIASES to the canonical org.
         const qKey = normalizeQueryKey(q);
         const aliasKey = ORG_ALIASES[qKey] ? normalizeQueryKey(ORG_ALIASES[qKey]) : null;
         const bestIsExact = !!best &&
@@ -626,19 +551,7 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
         let items = [];
         let upstreamCalls = 0;
         let total = null;
-        // pageQuery sends offset/page upstream, so what comes back IS the page and
-        // must not be sliced by offset again. Doing both returned an EMPTY page two
-        // while reporting total=1429 and hasMore=true. The UFC paths below fetch
-        // page 1 deliberately and re-rank in memory, so they page here instead.
         let upstreamPaged = true;
-        // Set for a game whose dedicated search endpoint already returns results
-        // in the right order (e.g. tennis: /tennis/players/search ranks Carlos
-        // Alcaraz first). The generic re-rank below fuzzy-scores every candidate
-        // against the query string with no notion of who is actually ranked, so
-        // "alcaraz" tied four players at nearly the same score and resorted the
-        // world #3 to fourth — behind three players the upstream had already
-        // correctly placed below him. Preserving push order keeps the upstream's
-        // answer instead of a worse one computed from less information.
         let preserveUpstreamOrder = false;
         const pageQuery = (extra = {}) => ({
             limit,
@@ -681,7 +594,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                     const res = await fetchJson(ctx, '/cs2/search', { query: { q, limit } });
                     upstreamCalls += 1;
                     if (res.ok) {
-                        // Unwrap the { success, data, meta } envelope before reading buckets.
                         const envelope = asRecord(res.data) ?? {};
                         const data = asRecord(envelope.data) ?? envelope;
                         if (type === 'any' || type === 'team') {
@@ -700,7 +612,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                         await listPath('/cs2/teams', 'team');
                     if (type === 'player' || type === 'any') {
                         if (q) {
-                            // /cs2/players list filters ignore q/search — use the dedicated search endpoint.
                             await listPath('/cs2/players/search', 'player');
                         }
                         else {
@@ -742,9 +653,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                         const envelope = asRecord(res.data) ?? {};
                         const data = asRecord(envelope.data) ?? envelope;
                         items.push(...extractRows(data.items ?? data).map((r) => entityRef(r, 'player', game)));
-                        // /tennis/players/search already ranks the best-known match first
-                        // (it has current_rank to break ties this tool's fuzzy scorer
-                        // cannot see); do not let the generic re-sort below undo that.
                         if (q)
                             preserveUpstreamOrder = true;
                     }
@@ -761,7 +669,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             }
             else if (game === 'cod') {
                 if (q) {
-                    // No offset goes upstream on this path, so page it here.
                     upstreamPaged = false;
                     const res = await fetchJson(ctx, '/cod/search', {
                         query: { q, limit, ...(type !== 'any' ? { type: type === 'team' ? 'org' : type } : {}) },
@@ -781,8 +688,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             }
             else if (game === 'ufc') {
                 if (q) {
-                    // Dedicated search ranks name/slug/nickname; /fighters ignores q.
-                    // Returns the whole match set for client re-ranking; page it here.
                     upstreamPaged = false;
                     const res = await fetchJson(ctx, '/ufc/search', { query: { q } });
                     upstreamCalls += 1;
@@ -861,7 +766,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                 rateLimit: e.headers,
             });
         }
-        // de-dupe by game+type+id; when q present re-sort by score if available
         const seen = new Set();
         items = items.filter((it) => {
             const key = `${it.game}:${it.type}:${it.id}`;
@@ -870,51 +774,15 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             seen.add(key);
             return true;
         });
-        /**
-         * Relevance floor.
-         *
-         * The upstream player/tournament search is a substring match with no floor
-         * of its own: `q=Sinner` returns ten rows, of which only "Jannik Sinner" and
-         * "Martin Sinner" have anything to do with the query. The tool scored them
-         * all and then SORTED rather than filtered, so "A Winner", "J Skinner",
-         * "E Skinner", "C Sinkler", "Dr Sinnett", "H C Skinner", "Mrs Skinner" and
-         * "J J Sinnott" came back as equals — an agent asking for one player got
-         * eight strangers to ignore, and a caller paging the results paid for them.
-         *
-         * rankScore already separates them cleanly (Jannik 100, Martin 48, every
-         * other row 0), so the floor is simply "must have matched something at all".
-         * It is applied only when a query was given: with no q this tool is a browse
-         * list, and a floor there would delete the catalogue.
-         */
         const scoreOf = (it) => typeof it.meta?.score === 'number'
             ? it.meta.score
             : rankScore(q, it.name, it.id, it.slug, it.meta?.nickname);
         const upstreamTotal = total;
         let droppedBelowFloor = [];
-        /**
-         * The upstream's own top ENTITY row is exempt from the floor.
-         *
-         * The upstream's dedicated search knows aliases the payload does not carry:
-         * `q=Nole` returns Novak Djokovic first, and rankScore cannot see why, so a
-         * pure floor would delete the correct answer and keep substring collisions
-         * instead.
-         *
-         * This used to be the global items[0], which was wrong: search_entities
-         * merges several sources CONCURRENTLY (for tennis, /players/search and
-         * /competitions), so whichever promise settled first decided which row got
-         * protected. The live gate caught it as a flaky "first result is Jannik
-         * Sinner" — a competition could land at index 0 and the alias protection
-         * would guard the wrong thing. Only entity rows (player/team/fighter) are
-         * alias-matched at all; tournaments are matched by name and have no
-         * nicknames, so taking the first entity row is both deterministic and the
-         * row the rule was written for.
-         */
         const ENTITY_TYPES = new Set(['player', 'team', 'fighter']);
         const protectedRow = q ? items.find((it) => ENTITY_TYPES.has(it.type)) ?? null : null;
         const protectedKey = protectedRow ? `${protectedRow.game}:${protectedRow.type}:${protectedRow.id}` : null;
         if (q) {
-            // Publish the score on every row, not just the ones the scored branch
-            // produced, so the floor is visible rather than mysterious.
             items = items.map((it) => {
                 const key = `${it.game}:${it.type}:${it.id}`;
                 const isProtected = protectedKey !== null && key === protectedKey;
@@ -935,9 +803,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
             if (droppedBelowFloor.length)
                 items = items.filter(keep);
         }
-        // An explicit (possibly rank-0) alias match beats a higher-scoring substring
-        // collision: the upstream's own top hit is the answer to a query we cannot
-        // score. This is what makes "Nole" resolve to Djokovic instead of M Canoles.
         if (q && !preserveUpstreamOrder) {
             items.sort((a, b) => {
                 const am = a.meta?.matchedBy === 'upstream-first' ? 1 : 0;
@@ -945,7 +810,6 @@ Example: { "game": "ufc", "q": "Jon Jones", "type": "fighter", "limit": 10 }`,
                 return bm - am || scoreOf(b) - scoreOf(a) || a.name.localeCompare(b.name);
             });
         }
-        // pagination over ranked result set
         const pageItems = upstreamPaged ? items.slice(0, limit) : items.slice(offset, offset + limit);
         const hasMore = upstreamPaged
             ? (total != null ? offset + pageItems.length < total : pageItems.length >= limit)

package/dist/tools/schedule.js

@@ -1,21 +1,6 @@
-/**
- * tennis_schedule — one day of tennis, scheduled and completed (TENNIS-26).
- *
- * WHY THIS EXISTS
- * /tennis/schedule and /tennis/matches/completed are the two routes that require
- * ?date=. They were the exact pair producing "route is broken" support tickets
- * from callers who omitted it, which is why the REST layer now returns a hint
- * with a working example URL. But neither route had a tool either — so an agent
- * driving the MCP had no way to ask "what tennis is on today?" at all.
- *
- * This tool owns the required date, defaults it to today, validates the format
- * before spending an upstream call, and on a bad date returns the same
- * paste-able example the REST hint does.
- */
 import { asRecord, clampInt, fetchJson, pickString, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, partialFromRejection, successEnvelope, } from '../envelope.js';
 import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
-/** ISO date, no time component, already validated by the caller. */
 function todayIso() {
     return new Date().toISOString().slice(0, 10);
 }
@@ -33,13 +18,6 @@ function normalizeScheduled(row) {
         round: pickString(r.round) ?? null,
         roundName: pickString(r.round_name) ?? null,
         startsAt: pickString(r.starts_at, r.commence_time, r.match_date) ?? null,
-        /**
-         * Historical days report every match at T00:00:00 with
-         * `start_time_known: false` — the date is real, the clock is a placeholder.
-         * Emitting the midnight without this flag invites a caller to render "12:00
-         * AM" for a semi-final that finished at 3pm. Null when the route does not
-         * state it (the completed half does not).
-         */
         startTimeKnown: typeof r.start_time_known === 'boolean' ? r.start_time_known : null,
         status: pickString(r.status, r.outcome) ?? null,
         player1: { id: pickString(p1.id, p1.player_id) ?? null, name: pickString(p1.name) ?? null },
@@ -47,7 +25,6 @@ function normalizeScheduled(row) {
         score: pickString(r.score, r.score_raw) ?? null,
     };
 }
-/** A row is "played" when the feed says so, in either spelling it uses. */
 function isPlayed(row) {
     const r = asRecord(row) ?? {};
     const s = (pickString(r.status, r.outcome) ?? '').toLowerCase();
@@ -114,8 +91,6 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         }
         const rawDate = typeof args.date === 'string' ? args.date.trim() : '';
         const date = rawDate || todayIso();
-        // Validate before spending an upstream call, and echo the same paste-able
-        // example the REST layer returns so the two surfaces teach identically.
         if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
             return errorEnvelope({
                 code: 'VALIDATION',
@@ -141,16 +116,6 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
         const limit = clampInt(args.limit, 20, 1, 50);
         const wantScheduled = includeRaw === 'both' || includeRaw === 'scheduled';
         const wantCompleted = includeRaw === 'both' || includeRaw === 'completed';
-        /**
-         * Ask for the whole day, then bound locally.
-         *
-         * /tennis/schedule honours ?limit= but /tennis/matches/completed ignores it,
-         * so passing `limit` upstream made `scheduledCount` mean "rows this call
-         * asked for" on one half and "rows the day held" on the other. Both halves
-         * are now fetched at the API's own page ceiling and sliced here, which makes
-         * scheduledCount/completedCount a fact about the day and *Returned a fact
-         * about the response.
-         */
         const upstreamPage = 200;
         const settled = await Promise.allSettled([
             wantScheduled
@@ -216,7 +181,6 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
                 message: String(compRes.reason).slice(0, 200),
             });
         }
-        // Both halves failed -> a real error, not a partial.
         if (rejected.length > 0 && scheduled.length === 0 && completed.length === 0) {
             const first = rejected[0];
             return errorEnvelope({
@@ -230,23 +194,8 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
                 recover: ['Check the date is a real calendar day', 'Retry, or widen include to both'],
             });
         }
-        /**
-         * /tennis/matches/completed IGNORES ?limit= — verified: `limit=3` returned
-         * all 13 rows of the day with page_size still 50. /tennis/schedule does
-         * honour it, but both halves are bounded here so one call site cannot drift
-         * from the other and `completedCount` stops being a number the caller asked
-         * to be smaller.
-         */
         const scheduledWindow = scheduled.slice(0, limit);
         const completedWindow = completed.slice(0, limit);
-        /**
-         * /tennis/schedule is the DAY's list, not an "upcoming" list: it carries
-         * matches that have already finished, with status COMPLETED. So the two
-         * halves of this response legitimately overlap, and the old key name
-         * ("scheduled") plus a status of COMPLETED inside it read as a
-         * contradiction. The overlap is now counted and the statuses summarised, so
-         * a caller can join or de-duplicate deliberately instead of discovering it.
-         */
         const completedBySchedule = scheduled.filter(isPlayed);
         const completedIds = new Set(completed
             .map((row) => pickString(asRecord(row)?.id, asRecord(row)?.match_id))
@@ -266,8 +215,6 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
             title: `Tennis — ${date}`,
             date,
             include: includeRaw,
-            // Everything the day's list returned, then the bounded window. Both are
-            // present so `scheduledCount` never silently means two different things.
             scheduled: scheduledWindow.map(normalizeScheduled),
             scheduledCount: scheduledTotal ?? scheduled.length,
             scheduledReturned: scheduledWindow.length,
@@ -290,8 +237,6 @@ Parallel-safe: yes. Upstream cost: 1 or 2.`,
                 : {}),
         };
         const upstreamCalls = (wantScheduled ? 1 : 0) + (wantCompleted ? 1 : 0);
-        // A half that failed is reported alongside the half that worked rather than
-        // being silently dropped: an empty scheduled[] means two different things.
         if (rejected.length > 0) {
             return successEnvelope({
                 source: 'tennis_schedule',

package/dist/tools/standings.js

@@ -1,16 +1,10 @@
-/**
- * standings
- */
 import { clampInt, extractRows, fetchJson, gameNotIncludedHint, asRecord, pickString, } from '../client.js';
 import { errorEnvelope, mapHttpToCode, newRequestId, successEnvelope, } from '../envelope.js';
 import { gameSchema, isPrimaryGame, limitSchema, parseGame, stringSchema, } from './types.js';
-/** Exported for offline UFC rank mapping tests. */
 export function normalizeStandingRow(row, index) {
     const r = asRecord(row) ?? {};
     const entity = asRecord(r.team) ?? asRecord(r.fighter) ?? asRecord(r.org) ?? r;
     const name = pickString(asRecord(entity)?.name, r.teamName, r.name, r.orgName, r.fighterName, r.player_name, asRecord(entity)?.slug) ?? `row-${index + 1}`;
-    // UFC official lists: champion has rank=null + rankText="C" (interim "IC"); contenders 1..15.
-    // Never fall back to index+1 for explicit null ranks — that produced two "#1" rows (champ + #1).
     const championStatus = pickString(r.championStatus, asRecord(entity)?.championStatus);
     const rankText = pickString(r.rankText);
     const isInterim = championStatus === 'interim' || rankText === 'IC' || r.isInterimChampion === true;
@@ -21,9 +15,6 @@ export function normalizeStandingRow(row, index) {
         isInterim;
     let rank;
     if (isChampion) {
-        // rank is numeric or null; the belt lives in rankText ("C"/"IC") and
-        // championStatus. Mixing a string into a numeric column forced every
-        // consumer to special-case it.
         rank = null;
     }
     else if (typeof r.rank === 'number') {
@@ -36,14 +27,13 @@ export function normalizeStandingRow(row, index) {
         rank = Number(rankText);
     }
     else if (r.rank === null) {
-        // Explicit null (UFC champ without flags, or unranked) — never invent index+1
         rank = rankText ?? null;
     }
     else if (rankText) {
         rank = rankText;
     }
     else if (r.rank === undefined && r.position === undefined) {
-        rank = index + 1; // last resort only when rank fields are absent entirely
+        rank = index + 1;
     }
     else {
         rank = null;
@@ -150,8 +140,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         }
         const game = gameParse.game;
         const limit = clampInt(args.limit, 50, 1, 100);
-        // Cursor is a plain offset. The whole table is in memory (UFC world scope
-        // is 176 rows), so nothing fancier is needed to walk every division.
         const offset = Math.max(0, Number.parseInt(String(args.cursor ?? '0'), 10) || 0);
         const scope = typeof args.scope === 'string' ? args.scope : undefined;
         const leagueId = typeof args.leagueId === 'string' ? args.leagueId : undefined;
@@ -160,7 +148,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         const season = typeof args.season === 'string' ? args.season : undefined;
         const stage = typeof args.stage === 'string' ? args.stage : undefined;
         const division = typeof args.division === 'string' ? args.division : undefined;
-        // Tennis rankings are pageable now that the API reports the real list size.
         const tennisPage = typeof args.page === 'number' && Number.isFinite(args.page) && args.page >= 1
             ? Math.trunc(args.page)
             : 1;
@@ -252,8 +239,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             }
         }
         else if (game === 'tennis') {
-            // Tennis "standings" = the latest ATP/WTA singles rankings, with
-            // rank_movement/previous_rank on every row. Pass tour via division.
             const tour = String(division ?? 'ATP').toUpperCase() === 'WTA' ? 'WTA' : 'ATP';
             path = '/tennis/standings';
             query = { tour, top_n: Math.min(limit, 100), page: tennisPage };
@@ -261,7 +246,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
             title = `${tour} singles rankings`;
         }
         else if (game === 'dota2') {
-            // No first-class standings — try team list worldRanking
             const res = await fetchJson(ctx, '/dota2/teams', { query: { limit } });
             if (!res.ok) {
                 return errorEnvelope({
@@ -332,12 +316,8 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 rateLimit: res.headers,
             });
         }
-        // Keep the unsliced count. UFC world scope is every division back to back,
-        // so limit=50 stops a third of the way through flyweight; a consumer needs
-        // to know that happened rather than receive total:null and guess.
         let allRows = extractRows(res.data).map((row, i) => normalizeStandingRow(row, i));
         let rows = allRows.slice(offset, offset + limit);
-        // UFC rankings may be nested by division
         if (game === 'ufc' && rows.length === 0) {
             const obj = asRecord(res.data) ?? {};
             const nested = [];
@@ -366,20 +346,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
         }
         const obj = asRecord(res.data);
         const upstreamMeta = asRecord(obj?.meta) ?? {};
-        /**
-         * `total` is the size of the published table, NOT the size of this page.
-         *
-         * This read `total: allRows.length` — the rows that happened to arrive — so
-         * a tennis table of 150 ranked players reported total:5, hasMore:false and
-         * looked complete and unpaginated. The API now returns the real figure
-         * (total/ranked_players/total_pages/has_next); this prefers it and only
-         * falls back to the received count when the route does not state one.
-         *
-         * These are read BEFORE the pagination block, because that block had the
-         * identical bug: it published total: allRows.length too, so fixing only the
-         * data block left pagination.total disagreeing with data.total on the same
-         * response. Two counts, one response, only one of them true.
-         */
         const upstreamTotal = typeof obj?.total === 'number' ? obj.total : null;
         const rankedPlayers = typeof obj?.ranked_players === 'number' ? obj.ranked_players : null;
         const totalPages = typeof obj?.total_pages === 'number' ? obj.total_pages : null;
@@ -438,7 +404,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                 hasMore: effectiveHasMore,
                 ...(game === 'tennis'
                     ? {
-                        // How deep the published list is, independent of this page.
                         rankedPlayers: rankedPlayers ?? effectiveTotal,
                         totalPages,
                         page: tennisPage,
@@ -446,15 +411,6 @@ Example: { "game": "cod", "season": "2026", "limit": 50 }`,
                     : {}),
                 ...(game === 'tennis'
                     ? {
-                        /**
-                         * Tennis rankings are a dated weekly SNAPSHOT, and the route names
-                         * the date in `ranking_date`. updatedAt was read only from
-                         * updatedAt/lastUpdated/meta.syncedAt/meta.fetchedAt, none of which
-                         * the tennis route emits, so every tennis table claimed
-                         * updatedAt:null while the very date a caller needs sat in the
-                         * payload — and a consumer showing a stale-looking table had no
-                         * way to find out it was a week old.
-                         */
                         rankingDate: pickString(obj?.ranking_date) ?? null,
                         updatedAt: pickString(obj?.updatedAt, obj?.lastUpdated, upstreamMeta.syncedAt, upstreamMeta.fetchedAt, obj?.ranking_date) ?? null,
                     }