@claudinho/core 0.10.0 → 0.10.1

package/dist/index.d.ts

@@ -331,9 +331,13 @@ interface BracketView {
     degraded: boolean;
     standingsDegraded: boolean;
     source?: string;
+    /** The bracket is a World Cup feature; off the bundle there is none (audit A03). */
+    unsupported?: true;
 }
 interface BracketResult {
     view: BracketView;
+    /** Off the bundle there is no bracket (audit A03); `view.stages` is empty. */
+    unsupported?: true;
     degraded: boolean;
     standingsDegraded: boolean;
     source?: string;
@@ -363,6 +367,17 @@ declare function fixturesByDate(dateISO: string, fixtures?: Match[], tz?: string
 declare function fixturesByTeam(code: string, fixtures?: Match[]): Match[];
 /** All fixtures in a group letter ("A".."L"). */
 declare function fixturesByGroup(group: string, fixtures?: Match[]): Match[];
+/**
+ * Eligible to be "the next match": the kickoff is still ahead AND the match is
+ * still going to be played. ONE predicate for every selector (`next`, the
+ * statusline countdown, the knockout-fixture cache, the market fixture, the
+ * refresher cadence) — a cancelled or postponed fixture keeps its kickoff, so
+ * a time-only check advertised it as the next game (audit A07). Finished is
+ * deliberately NOT a clause: under a real clock a finished match never has a
+ * future kickoff, and excluding it only changed seeded-clock replays of an
+ * ended tournament (measured on the 62-surface parity corpus).
+ */
+declare function isUpcoming(m: Match, now?: Date): boolean;
 /** The next upcoming fixture for a team at/after `from` (default now). */
 declare function nextFixtureForTeam(code: string, opts?: {
     from?: Date;
@@ -460,11 +475,27 @@ interface StandingRow {
     goalsAgainst: number;
     goalDiff: number;
     points: number;
+    /**
+     * The provider's own rank for this row. Present on every live row (the
+     * standings feed states it); absent on a computed or roster-at-zero table,
+     * which has no authority to rank anyone. Renderers print THIS, never the
+     * array position — on a partial table the two differ (audit A01).
+     */
+    rank?: number;
 }
 /** A group's table: the group letter ("A".."L") and its rows in standings order. */
 interface GroupStandings {
     group: string;
     rows: StandingRow[];
+    /**
+     * Present when the provider's table could not be read in full: `omitted` rows
+     * were refused (malformed, duplicate, or beyond the row cap). The readable rows
+     * stay usable, but a partial table carries no authority to confirm or project
+     * qualification, and every surface says it is partial (audit A01).
+     */
+    partial?: {
+        omitted: number;
+    };
 }
 /**
  * Compute a group table from a set of matches. Teams are seeded from every
@@ -530,7 +561,19 @@ interface ProviderAdapter {
         readonly kind: string;
         readonly status?: number;
         readonly throttled?: boolean;
+        /** For a throttle: how long the adapter will refuse to fetch (bounded). */
+        readonly retryAfterMs?: number;
     };
+    /** Optional: epoch ms until which the adapter refuses requests (a retained throttle). */
+    readonly cooldownUntil?: number;
+    /**
+     * Optional: arm the throttle window from outside — a fresh process reading
+     * the backoff its refresher persisted. Inside the window every call fails as
+     * a throttle without a request.
+     */
+    armCooldown?(untilMs: number): void;
+    /** Optional: be told when the throttle window is armed or extended. Returns unsubscribe. */
+    onCooldown?(listener: (untilMs: number) => void): () => void;
 }
 
 /**
@@ -659,6 +702,17 @@ interface MapContext {
 
 /** Default competition slug (the 2026 World Cup). */
 declare const DEFAULT_COMPETITION = "fifa.world";
+/**
+ * Provider cooldown after a 429/403 (audit A12): the window a throttled
+ * adapter refuses to fetch in. `Retry-After` is honoured in both RFC 9110 forms
+ * (delay-seconds and HTTP-date) up to MAX_COOLDOWN_MS — a longer request is
+ * capped, never silently shortened below the cap — and DEFAULT_COOLDOWN_MS
+ * applies when the header is absent or unreadable.
+ */
+declare const DEFAULT_COOLDOWN_MS: number;
+declare const MAX_COOLDOWN_MS: number;
+/** The cooldown a `Retry-After` header asks for, as milliseconds from `nowMs`, bounded. */
+declare function retryAfterMs(header: string | null | undefined, nowMs: number): number;
 /** Build an ESPN soccer base URL for a competition slug (e.g. "fifa.friendly"). */
 declare function competitionBase(slug: string): string;
 type ProviderErrorKind = 'http' | 'timeout' | 'parse';
@@ -670,6 +724,8 @@ type ProviderErrorKind = 'http' | 'timeout' | 'parse';
 declare class ProviderError extends Error {
     readonly kind: ProviderErrorKind;
     readonly status?: number;
+    /** For a throttle: how long the adapter will refuse to fetch (bounded). */
+    retryAfterMs?: number;
     constructor(message: string, kind: ProviderErrorKind, status?: number);
     /** 429/403 — the upstream is refusing us; retrying at the live cadence makes it worse. */
     get throttled(): boolean;
@@ -695,6 +751,8 @@ interface EspnAdapterOptions {
      * path, where group letters aren't needed and the extra call is wasteful.
      */
     enrichGroups?: boolean;
+    /** Clock, injectable for tests. Drives the throttle cooldown window. */
+    now?: () => number;
 }
 declare class EspnAdapter implements ProviderAdapter {
     private readonly opts;
@@ -718,7 +776,37 @@ declare class EspnAdapter implements ProviderAdapter {
      * throttle (persist a backoff) from an ordinary blip.
      */
     lastError?: ProviderError;
+    /**
+     * A retained throttle (audit A12): after a 429/403 every call inside the
+     * window throws the provider's last answer WITHOUT a request. A server-
+     * lifetime MCP adapter is covered by this alone; the CLI pre-arms each
+     * process from its persisted cache via `armCooldown`.
+     */
+    private cooldownUntilMs?;
+    private cooldownError?;
+    private readonly cooldownListeners;
+    private readonly clock;
     constructor(opts?: EspnAdapterOptions);
+    /** Epoch ms until which requests are refused, when a cooldown is armed. */
+    get cooldownUntil(): number | undefined;
+    /**
+     * Arm the cooldown from outside — a fresh CLI process reading the backoff
+     * its refresher persisted. The retained error reads as a throttle so every
+     * caller's `degraded` path and the refresher's persistence treat it as one.
+     */
+    armCooldown(untilMs: number, reason?: ProviderError): void;
+    /**
+     * Be told whenever the cooldown window is armed or EXTENDED — the way a
+     * caller persists a throttle that arrives from a still-running request after
+     * its own call already returned (review P2 on #128). Returns unsubscribe.
+     */
+    onCooldown(listener: (untilMs: number) => void): () => void;
+    /**
+     * The ONE place a window is set. Concurrent requests can each carry a
+     * Retry-After; the LATEST expiry wins — a shorter one arriving second must
+     * never shorten a longer active window (review P2 on #128).
+     */
+    private arm;
     fetchByDate(dateISO: string): Promise<Match[]>;
     fetchWindow(startDate: string, endDate: string): Promise<Match[]>;
     /**
@@ -753,6 +841,25 @@ declare class EspnAdapter implements ProviderAdapter {
     private get;
 }
 
+/**
+ * The ONE bounded JSON reader for provider responses (audit A11).
+ *
+ * A declared Content-Length is the cheap early exit; an undeclared (chunked)
+ * body used to be materialised in full before any cap applied, so a hijacked
+ * or misbehaving upstream could balloon the refresher's memory every cycle.
+ * Now the bytes actually consumed from the stream are counted, the read stops
+ * and cancels at the cap, and parsing happens only after the whole body has
+ * passed the bound. Test doubles without a body stream (`{ ok, json }`) still
+ * work: they carry no bytes to bound.
+ */
+declare class ResponseTooLargeError extends Error {
+    readonly bytes: number;
+    readonly limit: number;
+    constructor(bytes: number, limit: number);
+}
+/** Parse a JSON body of at most `maxBytes`, counting what is actually read. */
+declare function readJsonBounded(res: Response, maxBytes: number): Promise<unknown>;
+
 /**
  * The ESPN competition slug to fetch live state from. Defaults to the 2026
  * World Cup (`fifa.world`); override with CLAUDINHO_COMPETITION (e.g.
@@ -763,6 +870,16 @@ declare class EspnAdapter implements ProviderAdapter {
  * read the ONE resolver without importing each other.
  */
 declare function resolveCompetition(explicit?: string): string;
+/** The competition whose schedule ships bundled in the clients: the 2026 World Cup. */
+declare const BUNDLE_COMPETITION = "fifa.world";
+/**
+ * True when the bundled World Cup schedule applies to the active competition.
+ * Off the bundle, every path built on the skeleton (date merge, `match <id>`,
+ * `next`, the bracket, the knockout-fixture cache, the market fixture) must
+ * not read it: an empty foreign day showed 104 World Cup fixtures with foreign
+ * attribution (audit A03). Real per-competition support is 0.11 (2.1).
+ */
+declare function bundleApplies(competition?: string): boolean;
 
 /** Provider names {@link makeAdapter} can construct (the CLI validates against this). */
 declare const KNOWN_SOURCES: readonly ["espn"];
@@ -773,6 +890,8 @@ interface AdapterOptions {
      * it never renders group letters.
      */
     enrichGroups?: boolean;
+    /** Clock, injectable for tests; drives the provider cooldown window. */
+    now?: () => number;
 }
 /**
  * Construct a provider adapter for a `--source` name (default: espn). An
@@ -852,6 +971,8 @@ interface MatchByIdResult {
     match?: Match;
     degraded: boolean;
     source?: string;
+    /** Off the bundle a fixture list to look an id up in does not exist yet (audit A03). */
+    unsupported?: true;
 }
 /**
  * The fixture a team-scoped MARKET query should be about, live-confirmed.
@@ -871,6 +992,8 @@ interface NextFixtureResult {
     degraded: boolean;
     /** The provider that served the live overlay (absent when degraded). */
     source?: string;
+    /** Off the bundle "next" is built on a schedule we do not have yet (audit A03). */
+    unsupported?: true;
 }
 /**
  * A team's next UPCOMING fixture, LIVE-RESOLVED across the knockout phase.
@@ -895,6 +1018,8 @@ interface KnockoutFixturesResult {
     fixtures: Match[];
     /** True when the overlay fetch failed — caller must NOT cache this as "none". */
     degraded: boolean;
+    /** Off the bundle there is no knockout window to fetch (audit A03). */
+    unsupported?: true;
 }
 /**
  * The RESOLVED upcoming knockout fixtures from the live overlay — the data the
@@ -1479,6 +1604,10 @@ interface ShareTableInput {
     tables: readonly {
         group: string;
         rows: readonly StandingRow[];
+        /** Rows the provider served that could not be read (see GroupStandings). */
+        partial?: {
+            omitted: number;
+        };
     }[];
     /** Live-data provider name for attribution; omit when degraded/static. */
     source?: string;
@@ -1567,4 +1696,4 @@ declare function formatShareBracket(input: ShareBracketInput, options?: ShareBra
 /** Compact one-line-per-match bracket for narrow share contexts. */
 declare function formatBracketCompactLine(mv: BracketMatchView, opts?: BracketFormatOpts): string;
 
-export { BRACKET_STAGE_ORDER, type BatchResolution, type BoundedList, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketTopology, type BracketView, type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FlavorLevel, type FormatOpts, type GroupStandings, KNOCKOUT_EXTRA_TIME_MS, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type LiveResult, MARKET_COMPETITIONS, MAX_LABEL_COLUMNS, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type NextFixtureResult, type Outcome, type ParseResult, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, type ResolvedParticipant, SHARE_DISCLAIMER, SHARE_HASHTAG, type Selection, type ShareBracketInput, type ShareBracketOptions, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type Stage, type StandingRow, type StandingsResult, type Status, type Team, type TeamInfo, type TeamLookup, allFixtures, allTeams, ambiguous, asFlavorLevel, bounded, buildBracketTopology, buildBracketView, buildMarketSignal, byKickoff, cacheableKeys, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, definitiveNone, deriveFavorite, displayWidth, emptyBatch, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getStandings, groups, hasSaneDistribution, humanLabel, isCacheable, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isResolvedNation, isStaleSignal, isTournamentWindowOver, isValidDate, isValidTimeZone, knockoutWindow, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookupTeam, makeAdapter, makeMarketProvider, malformed, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSignalRendersFor, marketSourceLabel, marketsCoverCompetition, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseCachedMarketSignal, parseCachedMatch, parseCachedMatches, parseStandings, parseTeamSlot, parsedValue, productFlag, resolveCompetition, resolveMarketSource, resolveTz, resolvedValues, sanitizeBundledFixture, scoreline, sealMarketSignal, sealMatch, selectOne, stageLabel, stageLabelI18n, t, truncateVisible, unresolved, valid };
+export { BRACKET_STAGE_ORDER, BUNDLE_COMPETITION, type BatchResolution, type BoundedList, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketTopology, type BracketView, type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_COOLDOWN_MS, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FlavorLevel, type FormatOpts, type GroupStandings, KNOCKOUT_EXTRA_TIME_MS, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type LiveResult, MARKET_COMPETITIONS, MAX_COOLDOWN_MS, MAX_LABEL_COLUMNS, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type NextFixtureResult, type Outcome, type ParseResult, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, type ResolvedParticipant, ResponseTooLargeError, SHARE_DISCLAIMER, SHARE_HASHTAG, type Selection, type ShareBracketInput, type ShareBracketOptions, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type Stage, type StandingRow, type StandingsResult, type Status, type Team, type TeamInfo, type TeamLookup, allFixtures, allTeams, ambiguous, asFlavorLevel, bounded, buildBracketTopology, buildBracketView, buildMarketSignal, bundleApplies, byKickoff, cacheableKeys, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, definitiveNone, deriveFavorite, displayWidth, emptyBatch, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getStandings, groups, hasSaneDistribution, humanLabel, isCacheable, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isResolvedNation, isStaleSignal, isTournamentWindowOver, isUpcoming, isValidDate, isValidTimeZone, knockoutWindow, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookupTeam, makeAdapter, makeMarketProvider, malformed, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSignalRendersFor, marketSourceLabel, marketsCoverCompetition, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseCachedMarketSignal, parseCachedMatch, parseCachedMatches, parseStandings, parseTeamSlot, parsedValue, productFlag, readJsonBounded, resolveCompetition, resolveMarketSource, resolveTz, resolvedValues, retryAfterMs, sanitizeBundledFixture, scoreline, sealMarketSignal, sealMatch, selectOne, stageLabel, stageLabelI18n, t, truncateVisible, unresolved, valid };

package/dist/index.js

@@ -271,6 +271,8 @@ var EN = {
   "bracket.slot.tbd": "TBD",
   "live.data": "Live data: {source}",
   "standings.unavailable": "Live standings unavailable.",
+  "standings.partial": "Partial table \u2014 {n} rows could not be read.",
+  "competition.unsupported": "Not available for this competition yet.",
   "share.tryIt": "Try it: {line}",
   "stage.group": "Group {group}",
   "stage.groupStage": "Group stage",
@@ -301,6 +303,8 @@ var ES = {
   "bracket.slot.tbd": "Por definir",
   "live.data": "Datos en vivo: {source}",
   "standings.unavailable": "Tabla en vivo no disponible.",
+  "standings.partial": "Tabla parcial \u2014 no se pudieron leer {n} filas.",
+  "competition.unsupported": "A\xFAn no disponible para esta competici\xF3n.",
   "share.tryIt": "Pru\xE9balo: {line}",
   "stage.group": "Grupo {group}",
   "stage.groupStage": "Fase de grupos",
@@ -331,6 +335,8 @@ var PT = {
   "bracket.slot.tbd": "A definir",
   "live.data": "Dados ao vivo: {source}",
   "standings.unavailable": "Classifica\xE7\xE3o ao vivo indispon\xEDvel.",
+  "standings.partial": "Tabela parcial \u2014 {n} linhas n\xE3o puderam ser lidas.",
+  "competition.unsupported": "Ainda n\xE3o dispon\xEDvel para esta competi\xE7\xE3o.",
   "share.tryIt": "Experimente: {line}",
   "stage.group": "Grupo {group}",
   "stage.groupStage": "Fase de grupos",
@@ -361,6 +367,8 @@ var FR = {
   "bracket.slot.tbd": "\xC0 d\xE9finir",
   "live.data": "Donn\xE9es en direct : {source}",
   "standings.unavailable": "Classement en direct indisponible.",
+  "standings.partial": "Classement partiel \u2014 {n} lignes n'ont pas pu \xEAtre lues.",
+  "competition.unsupported": "Pas encore disponible pour cette comp\xE9tition.",
   "share.tryIt": "Essayez : {line}",
   "stage.group": "Groupe {group}",
   "stage.groupStage": "Phase de groupes",
@@ -2932,11 +2940,13 @@ function fixturesByGroup(group, fixtures = SCHEDULE) {
   const g = group.toUpperCase();
   return fixtures.filter((m) => (m.group ?? "").toUpperCase() === g).sort(byKickoff);
 }
+function isUpcoming(m, now = /* @__PURE__ */ new Date()) {
+  if (m.status === "CANCELLED" || m.status === "POSTPONED") return false;
+  return Date.parse(m.kickoff) >= now.getTime();
+}
 function nextFixtureForTeam(code, opts = {}) {
   const from = opts.from ?? /* @__PURE__ */ new Date();
-  return fixturesByTeam(code, opts.fixtures ?? SCHEDULE).find(
-    (m) => new Date(m.kickoff).getTime() >= from.getTime()
-  );
+  return fixturesByTeam(code, opts.fixtures ?? SCHEDULE).find((m) => isUpcoming(m, from));
 }
 var LIVE_WINDOW_MS = 140 * 6e4;
 var KNOCKOUT_EXTRA_TIME_MS = 60 * 6e4;
@@ -3381,7 +3391,7 @@ function toParticipant(raw) {
   const providerId = opaqueId(raw.team?.id, ESPN_ID);
   const known = productFlag(name) !== nationToFlag("");
   return valid(
-    providerId && known ? { kind: "team", providerId, team } : { kind: "slot", team }
+    providerId && known ? { kind: "team", providerId, team } : { kind: "slot", ...providerId ? { providerId } : {}, team }
   );
 }
 function mapStatus(st) {
@@ -3450,7 +3460,7 @@ function parseEspnEvent(raw, ctx = {}) {
   if (awayP.kind !== "valid") return awayP;
   const h = homeP.value;
   const a = awayP.value;
-  if (h.kind === "team" && a.kind === "team" && h.providerId === a.providerId) {
+  if (h.providerId !== void 0 && h.providerId === a.providerId) {
     return definitiveNone("both competitors are the same team");
   }
   const home = homeP.value.team;
@@ -3603,8 +3613,12 @@ function parseEspnStandings(raw) {
   const seenProviderIds = /* @__PURE__ */ new Set();
   for (const child of children) {
     const label = humanLabel(child?.name ?? child?.abbreviation);
-    const letter = label.match(/Group\s+([A-L])/i)?.[1]?.toUpperCase();
-    if (!letter) continue;
+    const letter = label.match(/Group\s+([A-L])(?![A-Za-z0-9])/i)?.[1]?.toUpperCase();
+    if (!letter) {
+      const rows = child?.standings?.entries;
+      if (Array.isArray(rows) && rows.length > 0) complete = false;
+      continue;
+    }
     if (seenGroups.has(letter)) {
       complete = false;
       continue;
@@ -3615,9 +3629,11 @@ function parseEspnStandings(raw) {
       complete = false;
       continue;
     }
+    let omitted = 0;
     if (rawEntries.length > MAX_GROUP_ROWS) {
       rowsTruncated = true;
       complete = false;
+      omitted += rawEntries.length - MAX_GROUP_ROWS;
     }
     const entries = takeBounded(rawEntries, MAX_GROUP_ROWS);
     const seenCodes = /* @__PURE__ */ new Map();
@@ -3627,6 +3643,7 @@ function parseEspnStandings(raw) {
       const r = entryToRow(e);
       if (r.kind !== "valid") {
         if (r.kind !== "definitive-none") complete = false;
+        omitted += 1;
         continue;
       }
       const { providerId, providerRank } = r.value;
@@ -3635,13 +3652,14 @@ function parseEspnStandings(raw) {
       const codeCollision = priorHadId !== void 0 && (providerId === void 0 || priorHadId === false);
       if (codeCollision || seenRanks.has(providerRank) || providerId !== void 0 && seenProviderIds.has(providerId)) {
         complete = false;
+        omitted += 1;
         continue;
       }
       seenCodes.set(code, providerId !== void 0);
       seenRanks.add(providerRank);
       if (providerId !== void 0) seenProviderIds.add(providerId);
       const { providerId: _dropId, providerRank: rank, ...row } = r.value;
-      ranked.push({ row, rank });
+      ranked.push({ row: { ...row, rank }, rank });
     }
     ranked.sort((a, b) => {
       if (a.rank && b.rank && a.rank !== b.rank) return a.rank - b.rank;
@@ -3653,7 +3671,11 @@ function parseEspnStandings(raw) {
       complete = false;
       continue;
     }
-    out.push({ group: letter, rows: ranked.map((x) => x.row) });
+    out.push({
+      group: letter,
+      rows: ranked.map((x) => x.row),
+      ...omitted > 0 ? { partial: { omitted } } : {}
+    });
   }
   return {
     items: out,
@@ -3665,12 +3687,75 @@ function parseEspnStandings(raw) {
   };
 }
 
+// src/adapters/http.ts
+var ResponseTooLargeError = class extends Error {
+  constructor(bytes, limit) {
+    super(`response body exceeds ${limit} bytes (${bytes} seen)`);
+    this.bytes = bytes;
+    this.limit = limit;
+    this.name = "ResponseTooLargeError";
+  }
+  bytes;
+  limit;
+};
+function isStream(v) {
+  return typeof v?.getReader === "function";
+}
+async function readJsonBounded(res, maxBytes) {
+  const r = res;
+  const declared = Number(r.headers?.get?.("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    if (isStream(r.body)) await r.body.cancel().catch(() => {
+    });
+    throw new ResponseTooLargeError(declared, maxBytes);
+  }
+  if (isStream(r.body)) {
+    const reader = r.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {
+        });
+        throw new ResponseTooLargeError(total, maxBytes);
+      }
+      chunks.push(value);
+    }
+    return JSON.parse(new TextDecoder().decode(Buffer.concat(chunks)));
+  }
+  if (typeof r.text === "function") {
+    const text = await r.text();
+    const size = Buffer.byteLength(text);
+    if (size > maxBytes) throw new ResponseTooLargeError(size, maxBytes);
+    return JSON.parse(text);
+  }
+  if (typeof r.json === "function") return r.json();
+  throw new TypeError("response has no readable body");
+}
+
 // src/adapters/espn.ts
 var ESPN_SOCCER = "https://site.api.espn.com/apis/site/v2/sports/soccer";
 var DEFAULT_COMPETITION = "fifa.world";
 var DEFAULT_BASE = `${ESPN_SOCCER}/${DEFAULT_COMPETITION}`;
-var USER_AGENT = `claudinho/${"0.10.0"} (+https://github.com/arturogarrido/claudinho)`;
+var USER_AGENT = `claudinho/${"0.10.1"} (+https://github.com/arturogarrido/claudinho)`;
 var MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+var DEFAULT_COOLDOWN_MS = 5 * 6e4;
+var MAX_COOLDOWN_MS = 15 * 6e4;
+function retryAfterMs(header, nowMs) {
+  if (typeof header !== "string" || header.trim() === "") return DEFAULT_COOLDOWN_MS;
+  const h = header.trim();
+  let ms;
+  if (/^\d+$/.test(h)) ms = Number(h) * 1e3;
+  else {
+    const at = Date.parse(h);
+    if (Number.isFinite(at)) ms = at - nowMs;
+  }
+  if (ms === void 0 || !Number.isFinite(ms)) return DEFAULT_COOLDOWN_MS;
+  return Math.min(Math.max(ms, 0), MAX_COOLDOWN_MS);
+}
 function competitionBase(slug) {
   return `${ESPN_SOCCER}/${slug}`;
 }
@@ -3679,6 +3764,8 @@ var STANDINGS_SHARE_MS = 3e4;
 var ProviderError = class extends Error {
   kind;
   status;
+  /** For a throttle: how long the adapter will refuse to fetch (bounded). */
+  retryAfterMs;
   constructor(message, kind, status) {
     super(message);
     this.name = "ProviderError";
@@ -3708,6 +3795,7 @@ function usableProviderItems(kind, parsed, hasUsableRecord = parsed.items.length
 var EspnAdapter = class {
   constructor(opts = {}) {
     this.opts = opts;
+    this.clock = opts.now ?? (() => Date.now());
     const expected = opts.expectedStandingsGroups ?? (opts.baseUrl === void 0 ? groups() : void 0);
     this.expectedStandingsGroups = expected ? [...expected] : void 0;
     this.standingsFallbackGroups = opts.baseUrl === void 0 && expected ? [...expected] : void 0;
@@ -3733,6 +3821,53 @@ var EspnAdapter = class {
    * throttle (persist a backoff) from an ordinary blip.
    */
   lastError;
+  /**
+   * A retained throttle (audit A12): after a 429/403 every call inside the
+   * window throws the provider's last answer WITHOUT a request. A server-
+   * lifetime MCP adapter is covered by this alone; the CLI pre-arms each
+   * process from its persisted cache via `armCooldown`.
+   */
+  cooldownUntilMs;
+  cooldownError;
+  cooldownListeners = /* @__PURE__ */ new Set();
+  clock;
+  /** Epoch ms until which requests are refused, when a cooldown is armed. */
+  get cooldownUntil() {
+    return this.cooldownUntilMs;
+  }
+  /**
+   * Arm the cooldown from outside — a fresh CLI process reading the backoff
+   * its refresher persisted. The retained error reads as a throttle so every
+   * caller's `degraded` path and the refresher's persistence treat it as one.
+   */
+  armCooldown(untilMs, reason) {
+    const nowMs = this.clock();
+    const error = reason ?? new ProviderError("ESPN request skipped: provider cooldown in effect", "http", 429);
+    error.retryAfterMs = Math.max(0, untilMs - nowMs);
+    this.arm(untilMs, error);
+  }
+  /**
+   * Be told whenever the cooldown window is armed or EXTENDED — the way a
+   * caller persists a throttle that arrives from a still-running request after
+   * its own call already returned (review P2 on #128). Returns unsubscribe.
+   */
+  onCooldown(listener) {
+    this.cooldownListeners.add(listener);
+    return () => {
+      this.cooldownListeners.delete(listener);
+    };
+  }
+  /**
+   * The ONE place a window is set. Concurrent requests can each carry a
+   * Retry-After; the LATEST expiry wins — a shorter one arriving second must
+   * never shorten a longer active window (review P2 on #128).
+   */
+  arm(untilMs, error) {
+    if (this.cooldownUntilMs !== void 0 && untilMs <= this.cooldownUntilMs) return;
+    this.cooldownUntilMs = untilMs;
+    this.cooldownError = error;
+    for (const listener of this.cooldownListeners) listener(untilMs);
+  }
   async fetchByDate(dateISO) {
     return this.fetchScoreboard(toEspnDate(dateISO));
   }
@@ -3820,6 +3955,11 @@ var EspnAdapter = class {
     return usableProviderItems("scoreboard", parsed);
   }
   async get(url) {
+    const nowMs = this.clock();
+    if (this.cooldownError && this.cooldownUntilMs !== void 0 && nowMs < this.cooldownUntilMs) {
+      this.lastError = this.cooldownError;
+      throw this.cooldownError;
+    }
     const doFetch = this.opts.fetchImpl ?? fetch;
     const controller = new AbortController();
     const timer = setTimeout(
@@ -3841,19 +3981,24 @@ var EspnAdapter = class {
         throw e?.name === "AbortError" ? new ProviderError(`ESPN request timed out: ${url}`, "timeout") : new ProviderError(`ESPN request failed: ${e?.message ?? e}`, "http");
       }
       if (!res.ok) {
-        throw new ProviderError(
+        const pe = new ProviderError(
           `ESPN request failed: ${res.status} ${res.statusText}`,
           "http",
           res.status
         );
-      }
-      const length = Number(res.headers?.get?.("content-length"));
-      if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
-        throw new ProviderError(`ESPN response too large: ${length} bytes`, "parse");
+        if (pe.throttled) {
+          const receiptMs = this.clock();
+          pe.retryAfterMs = retryAfterMs(res.headers?.get?.("retry-after"), receiptMs);
+          this.arm(receiptMs + pe.retryAfterMs, pe);
+        }
+        throw pe;
       }
       try {
-        return await res.json();
+        return await readJsonBounded(res, MAX_RESPONSE_BYTES);
       } catch (e) {
+        if (e instanceof ResponseTooLargeError) {
+          throw new ProviderError(`ESPN response too large: ${e.bytes} bytes`, "parse");
+        }
         throw new ProviderError(
           `ESPN response unparseable: ${e?.message ?? e}`,
           "parse"
@@ -4060,14 +4205,30 @@ function hasGroupStarted(group, tables) {
 function matchesPerTeamInGroup(teamCount) {
   return Math.max(0, teamCount - 1);
 }
-function isGroupStandingsComplete(table) {
-  const n = table?.rows.length ?? 0;
+function isGroupStandingsComplete(table, expectedTeams) {
+  if (!table || table.partial) return false;
+  const n = table.rows.length;
   if (n < 2) return false;
-  const required = matchesPerTeamInGroup(n);
+  if (expectedTeams !== void 0 && n < expectedTeams) return false;
+  const required = matchesPerTeamInGroup(Math.max(n, expectedTeams ?? n));
   return table.rows.every((r) => r.played >= required);
 }
+function bundledGroupSize(group) {
+  const codes = /* @__PURE__ */ new Set();
+  for (const m of fixturesByGroup(group)) {
+    codes.add(m.home.code);
+    codes.add(m.away.code);
+  }
+  return codes.size > 0 ? codes.size : void 0;
+}
 function isGroupComplete(group, tables) {
-  return isGroupStandingsComplete(tables.find((t2) => t2.group === group));
+  return isGroupStandingsComplete(
+    tables.find((t2) => t2.group === group),
+    bundledGroupSize(group)
+  );
+}
+function isGroupPartial(group, tables) {
+  return tables.find((t2) => t2.group === group)?.partial !== void 0;
 }
 function resolveWinner(match) {
   if (!isFinished(match.status)) return void 0;
@@ -4122,7 +4283,7 @@ function resolveSlot(ref, ctx, liveTeam, fixtureInMergedSet = false) {
       return tbd(ref.label);
     case "group": {
       if (liveParticipant) return liveParticipant;
-      if (!ctx.standingsDegraded && hasGroupStarted(ref.group, ctx.tables)) {
+      if (!ctx.standingsDegraded && !isGroupPartial(ref.group, ctx.tables) && hasGroupStarted(ref.group, ctx.tables)) {
         const team = teamFromStandings(ref.group, ref.position, ctx.tables);
         if (team) {
           const status = isGroupComplete(ref.group, ctx.tables) ? "confirmed" : "projected";
@@ -4762,6 +4923,10 @@ function resolveCompetition(explicit) {
   }
   return DEFAULT_COMPETITION;
 }
+var BUNDLE_COMPETITION = DEFAULT_COMPETITION;
+function bundleApplies(competition = resolveCompetition()) {
+  return competition === BUNDLE_COMPETITION;
+}
 
 // src/live.ts
 var KNOWN_SOURCES = ["espn"];
@@ -4770,7 +4935,7 @@ function makeAdapter(source = "espn", opts = {}) {
     case "espn": {
       const competition = resolveCompetition();
       const baseUrl = competition === DEFAULT_COMPETITION ? void 0 : competitionBase(competition);
-      return new EspnAdapter({ baseUrl, enrichGroups: opts.enrichGroups });
+      return new EspnAdapter({ baseUrl, enrichGroups: opts.enrichGroups, now: opts.now });
     }
     default:
       throw new Error(
@@ -4788,7 +4953,7 @@ function liveSourceLabel(source) {
   return known[source] ?? source.charAt(0).toUpperCase() + source.slice(1);
 }
 async function getMatchesForDate(adapter, dateISO) {
-  const base = allFixtures();
+  const base = bundleApplies() ? allFixtures() : [];
   const day = dateISO.slice(0, 10);
   try {
     const live = adapter.fetchWindow ? await adapter.fetchWindow(shiftUtcDate(day, -1), shiftUtcDate(day, 1)) : await adapter.fetchByDate(day);
@@ -4833,21 +4998,27 @@ function knockoutWindow() {
   return knockoutWindowMemo;
 }
 async function getBracket(adapter, opts = {}) {
+  if (!bundleApplies()) {
+    const view2 = { stages: [], degraded: false, standingsDegraded: false, unsupported: true };
+    return { view: view2, degraded: false, standingsDegraded: false, unsupported: true };
+  }
   const topology = loadBracketTopology();
   const base = allFixtures().filter((m) => m.stage !== "GROUP" && m.stage !== "FRIENDLY");
   let matches = base;
   let liveDegraded = true;
   let source;
-  try {
-    const win = knockoutWindow();
-    const live = adapter.fetchWindow && win ? await adapter.fetchWindow(win.start, win.end) : [];
-    matches = mergeLive(base, live);
-    liveDegraded = false;
-    source = adapter.name;
-  } catch {
+  const win = knockoutWindow();
+  if (adapter.fetchWindow && win) {
+    try {
+      const live = await adapter.fetchWindow(win.start, win.end);
+      matches = mergeLive(base, live);
+      liveDegraded = false;
+      source = adapter.name;
+    } catch {
+    }
   }
   const standings = await getStandings(adapter);
-  if (!source && !standings.degraded && standings.source) {
+  if (!source && !standings.degraded && standings.source && standings.tables.length > 0) {
     source = standings.source;
   }
   const view = buildBracketView(
@@ -4869,18 +5040,18 @@ async function getBracket(adapter, opts = {}) {
 }
 var EXTRA_TIME_SLACK_MS = 60 * 6e4;
 async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Date()) {
+  if (!bundleApplies()) return { match: void 0, degraded: false, unsupported: true };
   const nowMs = now.getTime();
   let fixtures = allFixtures();
   let overlayFailed = false;
-  try {
-    const win = knockoutWindow();
-    if (adapter.fetchWindow && win) {
-      fixtures = mergeLive(
-        fixtures,
-        await adapter.fetchWindow(win.start, win.end)
-      );
+  const win = knockoutWindow();
+  if (adapter.fetchWindow && win) {
+    try {
+      fixtures = mergeLive(fixtures, await adapter.fetchWindow(win.start, win.end));
+    } catch {
+      overlayFailed = true;
     }
-  } catch {
+  } else {
     overlayFailed = true;
   }
   const candidate = fixturesByTeam(code, fixtures).find((m) => {
@@ -4896,23 +5067,27 @@ async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Dat
   return { match: next, degraded: overlayFailed };
 }
 async function getNextFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Date()) {
+  if (!bundleApplies()) return { fixture: void 0, degraded: false, unsupported: true };
   const base = allFixtures();
   let matches = base;
   let degraded = true;
   let liveById;
-  try {
-    const win = knockoutWindow();
-    const live = adapter.fetchWindow && win ? await adapter.fetchWindow(win.start, win.end) : [];
-    matches = mergeLive(base, live);
-    degraded = false;
-    liveById = new Set(live.map((m) => m.id));
-  } catch {
+  const win = knockoutWindow();
+  if (adapter.fetchWindow && win) {
+    try {
+      const live = await adapter.fetchWindow(win.start, win.end);
+      matches = mergeLive(base, live);
+      degraded = false;
+      liveById = new Set(live.map((m) => m.id));
+    } catch {
+    }
   }
   const fixture = nextFixtureForTeam(code, { from: now, fixtures: matches });
   const source = fixture && liveById?.has(fixture.id) ? adapter.name : void 0;
   return { fixture, degraded, source };
 }
 async function getKnockoutFixtures(adapter, now = /* @__PURE__ */ new Date()) {
+  if (!bundleApplies()) return { fixtures: [], degraded: true, unsupported: true };
   const win = knockoutWindow();
   if (!adapter.fetchWindow || !win) return { fixtures: [], degraded: true };
   let live;
@@ -4921,13 +5096,13 @@ async function getKnockoutFixtures(adapter, now = /* @__PURE__ */ new Date()) {
   } catch {
     return { fixtures: [], degraded: true };
   }
-  const nowMs = now.getTime();
   const fixtures = live.filter(
-    (m) => m.stage !== "GROUP" && m.stage !== "FRIENDLY" && Date.parse(m.kickoff) >= nowMs && isResolvedNation(m.home) && isResolvedNation(m.away)
+    (m) => m.stage !== "GROUP" && m.stage !== "FRIENDLY" && isUpcoming(m, now) && isResolvedNation(m.home) && isResolvedNation(m.away)
   ).sort(byKickoff);
   return { fixtures, degraded: false };
 }
 async function getMatchById(adapter, id) {
+  if (!bundleApplies()) return { match: void 0, degraded: false, unsupported: true };
   const base = allFixtures().find((m) => m.id === id);
   if (!base) return { match: void 0, degraded: false };
   const day = base.kickoff.slice(0, 10);
@@ -5382,11 +5557,15 @@ var PolymarketProvider = class {
     if (!res.ok) {
       throw new Error(`Polymarket request failed: ${res.status} ${res.statusText}`);
     }
-    const length = Number(res.headers?.get?.("content-length"));
-    if (Number.isFinite(length) && length > MAX_RESPONSE_BYTES) {
-      throw new Error(`Polymarket response too large: ${length} bytes`);
+    let data;
+    try {
+      data = await readJsonBounded(res, MAX_RESPONSE_BYTES);
+    } catch (e) {
+      if (e instanceof ResponseTooLargeError) {
+        throw new Error(`Polymarket response too large: ${e.bytes} bytes`);
+      }
+      throw e;
     }
-    const data = await res.json();
     if (Array.isArray(data) && data.length > 1) {
       return ambiguous("slug returned more than one event");
     }
@@ -5804,10 +5983,13 @@ function formatShareTable(input, options = {}) {
       input.emptyNote ?? (input.degraded ? "Live standings unavailable." : "No standings available.")
     );
   } else {
-    for (const { group, rows } of input.tables) {
-      blocks.push(
-        [`Group ${group} \xB7 standings`, "", ...rows.map((r, i) => tableRow(r, i + 1))].join("\n")
-      );
+    for (const { group, rows, partial } of input.tables) {
+      const lines = [`Group ${group} \xB7 standings`, "", ...rows.map((r, i) => tableRow(r, r.rank ?? i + 1))];
+      if (partial) {
+        const n = partial.omitted;
+        lines.push("", `(partial table \u2014 ${n} row${n === 1 ? "" : "s"} unreadable; positions are the provider's ranks)`);
+      }
+      blocks.push(lines.join("\n"));
     }
     if (input.degraded) {
       blocks.push("(Live standings unavailable \u2014 group roster, not live results.)");
@@ -5949,7 +6131,9 @@ function formatBracketCompactLine(mv, opts = {}) {
 }
 export {
   BRACKET_STAGE_ORDER,
+  BUNDLE_COMPETITION,
   DEFAULT_COMPETITION,
+  DEFAULT_COOLDOWN_MS,
   DEFAULT_FLAVOR,
   DEFAULT_MAX_AGE_MS,
   EspnAdapter,
@@ -5959,9 +6143,11 @@ export {
   KNOWN_SOURCES,
   LIVE_WINDOW_MS,
   MARKET_COMPETITIONS,
+  MAX_COOLDOWN_MS,
   MAX_LABEL_COLUMNS,
   PolymarketProvider,
   ProviderError,
+  ResponseTooLargeError,
   SHARE_DISCLAIMER,
   SHARE_HASHTAG,
   allFixtures,
@@ -5972,6 +6158,7 @@ export {
   buildBracketTopology,
   buildBracketView,
   buildMarketSignal,
+  bundleApplies,
   byKickoff,
   cacheableKeys,
   competitionBase,
@@ -6018,6 +6205,7 @@ export {
   isResolvedNation,
   isStaleSignal,
   isTournamentWindowOver,
+  isUpcoming,
   isValidDate,
   isValidTimeZone,
   knockoutWindow,
@@ -6059,10 +6247,12 @@ export {
   parseTeamSlot,
   parsedValue,
   productFlag,
+  readJsonBounded,
   resolveCompetition,
   resolveMarketSource,
   resolveTz,
   resolvedValues,
+  retryAfterMs,
   sanitizeBundledFixture,
   scoreline,
   sealMarketSignal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/core",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Domain model, provider adapters (ESPN), standings, bundled schedule, and the read-only Polymarket market-signal sidecar powering Claudinho. Not affiliated with FIFA or Anthropic.",
   "type": "module",
   "license": "MIT",
@@ -54,11 +54,11 @@
   ],
   "devDependencies": {
     "@types/node": "^22.20.2",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.23.13",
     "typescript": "^5.7.0",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "tsup",