@claudinho/core 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,9 @@
 # @claudinho/core ⚽
 
-Shared domain model, data-provider adapters, and helpers for **Claudinho** —
-the 2026 men's football tournament in your dev environment. This is the engine
-behind [`@claudinho/cli`](https://www.npmjs.com/package/@claudinho/cli) and
+Shared domain model, data-provider adapters, a read-only market-signal sidecar,
+and helpers for **Claudinho** — the 2026 men's football tournament in your dev
+environment. This is the engine behind
+[`@claudinho/cli`](https://www.npmjs.com/package/@claudinho/cli) and
 [`@claudinho/mcp`](https://www.npmjs.com/package/@claudinho/mcp).
 
 > ⚠️ **Not affiliated with, endorsed by, or connected to FIFA or Anthropic.**
@@ -22,6 +23,7 @@ npm i @claudinho/core
 - **Live overlay** — `makeAdapter`, `getMatchesForDate`, `getLiveMatches`, `mergeLive` (static base + live state, with graceful degradation)
 - **Standings** — `computeStandings` (points / GD / GF tiebreak)
 - **Helpers** — emoji flags (`nationToFlag`), TZ-aware time (`formatKickoff`, `countdown`, `localDate`), location strings (`matchLocation`), localized commentary flair (`matchFlavor` / `FlavorLevel`), validators (`isValidDate`, `isValidTimeZone`)
+- **Prediction-market signals (sidecar)** — read-only market odds kept *separate* from `Match`: the `MarketSignal` / `MarketProvider` model, the `PolymarketProvider` (public Gamma data only — no auth/trading/links; event slugs auto-derived per fixture, validation fails closed), a `FakeMarketProvider`, `makeMarketProvider`, `getMarketSignal` / `getMarketSignals`, the `isReliableMarketSignal` gate, and approved-copy formatters (`marketFavoriteText`, `marketProbabilityText`, `marketBlock`). Informational only — never betting advice.
 
 ## Example
 

package/dist/index.d.ts

@@ -394,7 +394,15 @@ interface LiveResult {
     matches: Match[];
     /** True when the provider call failed and we fell back to static data. */
     degraded: boolean;
+    /**
+     * The live-data provider that served this result (e.g. "espn"), for
+     * attribution. Absent when `degraded` — the bundled static schedule, served
+     * by no live provider, must not be attributed to one.
+     */
+    source?: string;
 }
+/** Human label for a live-data provider name (attribution). Text only. */
+declare function liveSourceLabel(source: string): string;
 /**
  * Matches for a date, preferring live provider data, falling back to the static
  * schedule on any provider/network error (graceful degradation).
@@ -403,4 +411,302 @@ declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string): P
 /** Currently-live matches; empty + degraded on error. */
 declare function getLiveMatches(adapter: ProviderAdapter): Promise<LiveResult>;
 
-export { DEFAULT_COMPETITION, DEFAULT_FLAVOR, EspnAdapter, type EspnAdapterOptions, FLAVOR_LEVELS, type FlavorLevel, type FormatOpts, type LedgerRow, type LiveResult, type MapContext, type Match, type MatchEvent, type Outcome, type ProviderAdapter, type ProviderCapabilities, type PunditPick, type Stage, type StandingRow, type Status, type Team, allFixtures, asFlavorLevel, byKickoff, competitionBase, computeStandings, countdown, fixturesByDate, fixturesByGroup, fixturesByTeam, flagEmoji, formatKickoff, getLiveMatches, getMatchesForDate, groups, isFinished, isFlavorLevel, isLive, isValidDate, isValidTimeZone, localDate, makeAdapter, mapEspnEvent, matchFlavor, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, outcomeFromScore, resolveCompetition, resolveTz, scoreline };
+/**
+ * Prediction-market "signal" model — a *sidecar* to Match, deliberately never
+ * embedded in it. Market data has different freshness, reliability, failure,
+ * and legal semantics than tournament facts, so it lives in its own folder and
+ * is keyed back to a match by id. This keeps prediction-market context off the
+ * hot paths (statusline, hook) by construction rather than by remembering a flag.
+ *
+ * Read-only by design: providers fetch public market data only — no wallet,
+ * no auth, no order placement. Nothing here models trading.
+ */
+
+/** Which match result a priced line refers to (home win / draw / away win). */
+type MarketOutcomeKind = 'home' | 'draw' | 'away' | 'other';
+/** One priced outcome of a match market. */
+interface MarketOutcome {
+    kind: MarketOutcomeKind;
+    /** Team code for 'home'/'away' (e.g. "MEX"); absent for draw/other. */
+    teamCode?: string;
+    /** Label as the source displays it (e.g. "Mexico", "Draw"). */
+    label: string;
+    /** Market-implied probability, normalized to [0,1] (sums to ~1 across a market). */
+    probability: number;
+}
+/** How strongly the market leans toward its top outcome. */
+type FavoriteStrength = 'close' | 'slight' | 'clear';
+/** The top outcome plus its strength bucket. */
+interface MarketFavorite {
+    kind: 'home' | 'draw' | 'away';
+    teamCode?: string;
+    probability: number;
+    strength: FavoriteStrength;
+}
+/** A normalized prediction-market reading for a single match. */
+interface MarketSignal {
+    /** Claudinho match id this signal maps to. */
+    matchId: string;
+    /** Provider name (e.g. "polymarket"). */
+    source: string;
+    /**
+     * Opaque source market id, for debugging and mapping only. Deliberately never
+     * surfaced as a clickable link in v1 (see the no-outbound-links guardrail).
+     */
+    sourceMarketId?: string;
+    /** When the source last priced the market (ISO 8601 UTC). */
+    asOf: string;
+    /** When Claudinho fetched it (ISO 8601 UTC). */
+    fetchedAt: string;
+    /** Priced outcomes, normalized so positive probabilities sum to ~1. */
+    outcomes: MarketOutcome[];
+    /** Top outcome, when one can be determined from a clean mapping. */
+    favorite?: MarketFavorite;
+    /** Source liquidity, when available (provider units; used only for gating). */
+    liquidity?: number;
+    /** Source 24h volume, when available (provider units). */
+    volume24h?: number;
+    /** True when the snapshot is older than the freshness window. */
+    stale: boolean;
+    /** True when the market does not map cleanly to the displayed home/draw/away result. */
+    ambiguous: boolean;
+}
+/** Tunables for reliability gating and provider fetch behavior. */
+interface MarketSignalOptions {
+    /** "Now" for staleness math; defaults to the current time. */
+    now?: Date;
+    /** Minimum source liquidity required to treat a signal as reliable. */
+    minLiquidity?: number;
+    /** Max age (ms) before a signal is considered stale. */
+    maxAgeMs?: number;
+    /**
+     * Bypass reliability gates — used by the dedicated `markets` surface, which
+     * may show a thin/stale market *with a caveat*. Default surfaces never set this.
+     */
+    includeUnreliable?: boolean;
+    /**
+     * Max total wall-clock (ms) for a batch `findSignals` before it stops early.
+     * Keeps optional market enrichment from blocking core fixture output.
+     */
+    deadlineMs?: number;
+    /** Per-request fetch timeout (ms) override for the provider. */
+    timeoutMs?: number;
+}
+/**
+ * Result of a batch lookup. `checked` is the set of match ids the provider
+ * DEFINITIVELY resolved (reached the source and found no usable market, or the
+ * fixture is unmappable) — distinct from matches that errored or were skipped by
+ * the deadline. Callers negative-cache only `checked` ids, so a transient
+ * provider/network failure never suppresses a valid signal.
+ */
+interface MarketSignalsResult {
+    signals: Map<string, MarketSignal>;
+    checked: Set<string>;
+}
+/**
+ * A prediction-market provider. A *separate* swap-point from ProviderAdapter
+ * (which supplies match data): different cadence, reliability, and legal
+ * posture. Implementations fetch public market data only.
+ */
+interface MarketProvider {
+    readonly name: string;
+    /** Signal for one match, or undefined when nothing maps cleanly. */
+    findSignal(match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
+    /** Batch form; signals plus the set of definitively-checked ids. */
+    findSignals(matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
+}
+
+/**
+ * Probability normalization + the reliability gate. `isReliableMarketSignal` is
+ * the single primitive every default-on surface keys off: "show only when
+ * reliable, otherwise omit silently."
+ */
+
+/** Default freshness window: a signal older than this is stale (15 minutes). */
+declare const DEFAULT_MAX_AGE_MS: number;
+/**
+ * Re-scale outcome probabilities so the positive ones sum to 1. This removes
+ * market "vig" (raw prices sum to >1) and is scale-agnostic: inputs may be
+ * 0..1 or 0..100 and the result is a clean [0,1] distribution. Non-finite or
+ * non-positive inputs collapse to 0.
+ */
+declare function normalizeOutcomes(outcomes: MarketOutcome[]): MarketOutcome[];
+/** Bucket a favorite's probability into a strength label. */
+declare function favoriteStrength(probability: number): FavoriteStrength;
+/** Pick the top home/draw/away outcome as the favorite, if one exists. */
+declare function deriveFavorite(outcomes: MarketOutcome[]): MarketFavorite | undefined;
+/**
+ * Does this market cleanly price the displayed home/draw/away result? Rejects
+ * "to advance"/"to win tournament"-style markets (an 'other' outcome), markets
+ * whose team codes don't match the fixture, and group-stage markets missing a
+ * draw line (a 90' group result must price the draw).
+ */
+declare function mapsCleanly(match: Match, outcomes: MarketOutcome[]): boolean;
+/** Sanity check: ≥2 priced outcomes whose probabilities sum to ~1. */
+declare function hasSaneDistribution(outcomes: MarketOutcome[]): boolean;
+/** Is the signal older than the freshness window? Unparseable timestamps are stale. */
+declare function isStaleSignal(signal: MarketSignal, options?: MarketSignalOptions): boolean;
+/**
+ * The load-bearing gate. A signal is reliable only when it is unambiguous, has
+ * a determinable favorite, is a sane distribution, is fresh, and (when a floor
+ * is configured) liquid enough. `includeUnreliable` bypasses all of it.
+ */
+declare function isReliableMarketSignal(signal: MarketSignal, options?: MarketSignalOptions): boolean;
+/** Inputs a provider supplies to build a normalized, gated signal. */
+interface BuildSignalInput {
+    match: Match;
+    source: string;
+    sourceMarketId?: string;
+    asOf: string;
+    fetchedAt?: string;
+    /** Raw outcomes (any positive scale); normalized internally. */
+    outcomes: MarketOutcome[];
+    liquidity?: number;
+    volume24h?: number;
+    /** Force-flag as ambiguous (e.g. the source title didn't parse to a clean result). */
+    ambiguous?: boolean;
+    now?: Date;
+    maxAgeMs?: number;
+}
+/**
+ * Construct a normalized MarketSignal from a provider's raw parts. Centralizes
+ * normalization, clean-mapping detection, favorite derivation, and staleness so
+ * every provider produces identically-shaped, gate-ready signals.
+ */
+declare function buildMarketSignal(input: BuildSignalInput): MarketSignal;
+
+/**
+ * Provider-neutral text snippets for market signals — the single home for the
+ * approved copy bank, shared verbatim by CLI and MCP. Keeping copy here (not in
+ * each client) is a legal control: the language stays factual and never says
+ * "bet", "value", "edge", "lock", etc. Display precision is whole-number
+ * percent on purpose, to avoid implying false precision.
+ */
+
+/** Human label for the data source (text only — never a logo). */
+declare function marketSourceLabel(source: string): string;
+/** One-line favorite read, drawn only from the approved copy bank. */
+declare function marketFavoriteText(signal: MarketSignal, match: Match): string;
+/** "Mexico 56% · Draw 25% · South Africa 19%" in home·draw·away reading order. */
+declare function marketProbabilityText(signal: MarketSignal, match: Match): string;
+/** "Source: Polymarket · updated 14:32 UTC". */
+declare function marketAttributionText(signal: MarketSignal): string;
+/** Compact one-liner for an inline annotation under a match row. */
+declare function marketLine(signal: MarketSignal, match: Match): string;
+/**
+ * Multi-line detail block (the caller indents/colorizes). Used by `match <id>`
+ * and the dedicated `markets` command. Always carries attribution and the
+ * informational-only caveat; prepends a stale warning when applicable.
+ */
+declare function marketBlock(signal: MarketSignal, match: Match): string[];
+
+/**
+ * Provider factory + graceful-degradation wrappers, mirroring `live.ts`'s
+ * getMatchesForDate contract: a market signal is optional enrichment, so any
+ * provider/network/parse error degrades to "no signal" and never throws.
+ */
+
+/**
+ * Resolve the market-data source: explicit arg > CLAUDINHO_MARKETS_SOURCE env >
+ * 'polymarket' (mirrors resolveCompetition). Set CLAUDINHO_MARKETS_SOURCE=fake
+ * to preview the UX with synthetic, clearly-labeled "demo data" odds.
+ */
+declare function resolveMarketSource(explicit?: string): string;
+/**
+ * Construct a market-signal provider. Defaults to the Polymarket public-data
+ * adapter; honors CLAUDINHO_MARKETS_SOURCE ('fake' = network-free synthetic
+ * demo data; 'none'/'off' = network-free no-op). Tests usually inject directly.
+ */
+declare function makeMarketProvider(source?: string): MarketProvider;
+/** Fetch one match's signal; never throws — undefined on any error. */
+declare function getMarketSignal(provider: MarketProvider, match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
+/** Batch fetch; never throws — empty result (nothing checked) on any error. */
+declare function getMarketSignals(provider: MarketProvider, matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
+
+/**
+ * A network-free MarketProvider for tests and local UX validation. Returns
+ * explicitly-provided signals and (optionally) deterministically synthesizes
+ * plausible-but-fake odds so every surface can be exercised without any live
+ * API. Always labeled `source: 'fake'` so it can never masquerade as real data.
+ */
+
+interface FakeMarketProviderOptions {
+    /** Pre-built signals keyed by matchId; returned verbatim when present. */
+    signals?: Record<string, MarketSignal>;
+    /** When true, synthesize a deterministic signal for any unmapped match. */
+    synthesize?: boolean;
+    /** "Now" used when synthesizing timestamps (keeps tests deterministic). */
+    now?: Date;
+}
+declare class FakeMarketProvider implements MarketProvider {
+    private readonly opts;
+    readonly name = "fake";
+    constructor(opts?: FakeMarketProviderOptions);
+    findSignal(match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
+    findSignals(matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
+    private synthesize;
+}
+
+/**
+ * Polymarket public-data adapter — read-only prediction-market signals.
+ *
+ * STRICT read-only by design: it touches only the public Gamma events/markets
+ * data endpoint. No auth, no wallet, no CLOB/order endpoints, no trading, and no
+ * outbound links (sourceMarketId is opaque, never a URL). Any network/parse/host
+ * error degrades to "no signal" — it never throws.
+ *
+ * Payload model (verified against the live Gamma API, see
+ * docs/POLYMARKET_MARKET_PREDICTIONS.md): a World Cup match is a Gamma EVENT
+ * (`fifwc-{home}-{away}-{date}`) whose payload carries the three moneyline
+ * BINARY markets — home win / draw / away win. Each is `outcomes: ["Yes","No"]`
+ * and the outcome's probability is its "Yes" price.
+ *
+ * Mapping is by event slug, which is deterministic — so by default the slug is
+ * DERIVED from the fixture (team codes + UTC date) and every match attempts
+ * enrichment. A hand-curated entry in mapping.2026.json overrides the derived
+ * slug for the rare fixture whose slug doesn't follow the pattern. Because the
+ * slug is a guess, validation FAILS CLOSED: the returned event must match the
+ * requested slug, line up on kickoff, expose the right moneyline markets, and
+ * resolve in regular time — otherwise no signal is produced.
+ */
+
+/**
+ * Optional override of the derived event slug for a fixture whose Polymarket
+ * slug doesn't follow `fifwc-{home}-{away}-{date}` (e.g. an abbreviation that
+ * differs from the FIFA code). Most matches need no entry — the slug is derived.
+ */
+interface MarketMapping {
+    /** Gamma event slug, e.g. "fifwc-mex-rsa-2026-06-11". */
+    eventSlug: string;
+    /** Optional Gamma event id (diagnostics; the slug is the lookup key). */
+    eventId?: string;
+}
+type MarketMappingTable = Record<string, MarketMapping>;
+interface PolymarketProviderOptions {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /** Base URL; must resolve to an allow-listed host. */
+    baseUrl?: string;
+    /** Override the bundled mapping table (tests / future gateway). */
+    mapping?: MarketMappingTable;
+    now?: Date;
+    maxAgeMs?: number;
+}
+declare class PolymarketProvider implements MarketProvider {
+    private readonly opts;
+    readonly name = "polymarket";
+    constructor(opts?: PolymarketProviderOptions);
+    findSignal(match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
+    findSignals(matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
+    /**
+     * Resolve one match. `checked` distinguishes a DEFINITIVE result (reached the
+     * source and found no usable market, or the fixture is unmappable) from a
+     * provider/network error — so transient failures are retried, not
+     * negative-cached.
+     */
+    private resolveOne;
+    private fetchEvent;
+    private toSignal;
+}
+
+export { 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 LedgerRow, type LiveResult, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchEvent, type Outcome, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, type PunditPick, type Stage, type StandingRow, type Status, type Team, allFixtures, asFlavorLevel, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, deriveFavorite, favoriteStrength, fixturesByDate, fixturesByGroup, fixturesByTeam, flagEmoji, formatKickoff, getLiveMatches, getMarketSignal, getMarketSignals, getMatchesForDate, groups, hasSaneDistribution, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isStaleSignal, isValidDate, isValidTimeZone, liveSourceLabel, localDate, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketLine, marketProbabilityText, marketSourceLabel, matchFlavor, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeOutcomes, outcomeFromScore, resolveCompetition, resolveMarketSource, resolveTz, scoreline };

package/dist/index.js

@@ -2848,12 +2848,16 @@ function mergeLive(base, live) {
   for (const m of live) byId.set(m.id, m);
   return [...byId.values()];
 }
+function liveSourceLabel(source) {
+  const known = { espn: "ESPN" };
+  return known[source] ?? source.charAt(0).toUpperCase() + source.slice(1);
+}
 async function getMatchesForDate(adapter, dateISO) {
   const base = 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);
-    return { matches: mergeLive(base, live), degraded: false };
+    return { matches: mergeLive(base, live), degraded: false, source: adapter.name };
   } catch {
     return { matches: base, degraded: true };
   }
@@ -2864,46 +2868,501 @@ function shiftUtcDate(dateISO, days) {
 }
 async function getLiveMatches(adapter) {
   try {
-    return { matches: await adapter.fetchLive(), degraded: false };
+    return { matches: await adapter.fetchLive(), degraded: false, source: adapter.name };
   } catch {
     return { matches: [], degraded: true };
   }
 }
+
+// src/markets/normalize.ts
+var DEFAULT_MAX_AGE_MS = 15 * 6e4;
+function normalizeOutcomes(outcomes) {
+  const sum = outcomes.reduce(
+    (s, o) => s + (Number.isFinite(o.probability) && o.probability > 0 ? o.probability : 0),
+    0
+  );
+  if (sum <= 0) return outcomes.map((o) => ({ ...o, probability: 0 }));
+  return outcomes.map((o) => ({
+    ...o,
+    probability: Number.isFinite(o.probability) && o.probability > 0 ? o.probability / sum : 0
+  }));
+}
+function favoriteStrength(probability) {
+  if (probability >= 0.65) return "clear";
+  if (probability >= 0.52) return "slight";
+  return "close";
+}
+function deriveFavorite(outcomes) {
+  let top;
+  for (const o of outcomes) {
+    if (o.kind === "other") continue;
+    if (!top || o.probability > top.probability) top = o;
+  }
+  if (!top || top.probability <= 0 || top.kind === "other") return void 0;
+  return {
+    kind: top.kind,
+    teamCode: top.teamCode,
+    probability: top.probability,
+    strength: favoriteStrength(top.probability)
+  };
+}
+function mapsCleanly(match, outcomes) {
+  if (outcomes.some((o) => o.kind === "other")) return false;
+  const home = outcomes.find((o) => o.kind === "home");
+  const away = outcomes.find((o) => o.kind === "away");
+  const draw = outcomes.find((o) => o.kind === "draw");
+  if (!home || !away) return false;
+  if (home.teamCode && home.teamCode.toUpperCase() !== match.home.code.toUpperCase()) {
+    return false;
+  }
+  if (away.teamCode && away.teamCode.toUpperCase() !== match.away.code.toUpperCase()) {
+    return false;
+  }
+  if (match.stage === "GROUP" && !draw) return false;
+  return true;
+}
+function hasSaneDistribution(outcomes) {
+  const priced = outcomes.filter((o) => Number.isFinite(o.probability) && o.probability > 0);
+  if (priced.length < 2) return false;
+  const sum = priced.reduce((s, o) => s + o.probability, 0);
+  return sum > 0.97 && sum < 1.03;
+}
+function isStaleSignal(signal, options = {}) {
+  const maxAge = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const asOf = Date.parse(signal.asOf);
+  if (!Number.isFinite(asOf)) return true;
+  const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
+  return now - asOf > maxAge;
+}
+function isReliableMarketSignal(signal, options = {}) {
+  if (options.includeUnreliable) return true;
+  if (signal.ambiguous) return false;
+  if (!signal.favorite) return false;
+  if (!hasSaneDistribution(signal.outcomes)) return false;
+  if (signal.stale || isStaleSignal(signal, options)) return false;
+  if (options.minLiquidity != null) {
+    if (signal.liquidity == null || signal.liquidity < options.minLiquidity) return false;
+  }
+  return true;
+}
+function buildMarketSignal(input) {
+  const outcomes = normalizeOutcomes(input.outcomes);
+  const ambiguous = input.ambiguous === true || !mapsCleanly(input.match, outcomes);
+  const favorite = ambiguous ? void 0 : deriveFavorite(outcomes);
+  const signal = {
+    matchId: input.match.id,
+    source: input.source,
+    sourceMarketId: input.sourceMarketId,
+    asOf: input.asOf,
+    fetchedAt: input.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    outcomes,
+    favorite,
+    liquidity: input.liquidity,
+    volume24h: input.volume24h,
+    stale: false,
+    ambiguous
+  };
+  signal.stale = isStaleSignal(signal, { now: input.now, maxAgeMs: input.maxAgeMs });
+  return signal;
+}
+
+// src/markets/format.ts
+function pct(p) {
+  return Math.round(p * 100);
+}
+function marketSourceLabel(source) {
+  if (source === "polymarket") return "Polymarket";
+  if (source === "fake") return "demo data";
+  return source.charAt(0).toUpperCase() + source.slice(1);
+}
+function outcomeLabel(o, match) {
+  if (o.kind === "home") return match.home.name;
+  if (o.kind === "away") return match.away.name;
+  if (o.kind === "draw") return "Draw";
+  return o.label;
+}
+function utcHhmm(iso) {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return "";
+  return `${new Date(t).toISOString().slice(11, 16)} UTC`;
+}
+function marketFavoriteText(signal, match) {
+  const fav = signal.favorite;
+  if (!fav || fav.strength === "close") return "Prediction markets see this match as close.";
+  if (fav.kind === "draw") return "Prediction markets see a draw as the top outcome.";
+  const name = fav.kind === "home" ? match.home.name : match.away.name;
+  return fav.strength === "clear" ? `Prediction markets favor ${name}.` : `Prediction markets slightly favor ${name}.`;
+}
+function marketProbabilityText(signal, match) {
+  const order = ["home", "draw", "away"];
+  const parts = [];
+  for (const kind of order) {
+    const o = signal.outcomes.find((x) => x.kind === kind);
+    if (o) parts.push(`${outcomeLabel(o, match)} ${pct(o.probability)}%`);
+  }
+  for (const o of signal.outcomes) {
+    if (o.kind === "other") parts.push(`${outcomeLabel(o, match)} ${pct(o.probability)}%`);
+  }
+  return parts.join(" \xB7 ");
+}
+function marketAttributionText(signal) {
+  const time = utcHhmm(signal.asOf);
+  const src = `Source: ${marketSourceLabel(signal.source)}`;
+  return time ? `${src} \xB7 updated ${time}` : src;
+}
+function marketLine(signal, match) {
+  return `Market: ${marketProbabilityText(signal, match)} \xB7 ${marketSourceLabel(
+    signal.source
+  )} \xB7 informational only`;
+}
+function marketBlock(signal, match) {
+  const lines = [];
+  if (signal.stale) lines.push("Market signal is stale; the reading may be out of date.");
+  lines.push(marketFavoriteText(signal, match));
+  lines.push(marketProbabilityText(signal, match));
+  lines.push(`${marketAttributionText(signal)} \xB7 informational only`);
+  return lines;
+}
+
+// src/markets/fake.ts
+var FakeMarketProvider = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  opts;
+  name = "fake";
+  async findSignal(match, options) {
+    const preset = this.opts.signals?.[match.id];
+    if (preset) return preset;
+    if (this.opts.synthesize) return this.synthesize(match, options);
+    return void 0;
+  }
+  async findSignals(matches, options) {
+    const signals = /* @__PURE__ */ new Map();
+    const checked = /* @__PURE__ */ new Set();
+    for (const m of matches) {
+      checked.add(m.id);
+      const s = await this.findSignal(m, options);
+      if (s) signals.set(m.id, s);
+    }
+    return { signals, checked };
+  }
+  synthesize(match, options) {
+    const seed = hash(`${match.home.code}-${match.away.code}`);
+    const home = 0.3 + seed % 33 / 100;
+    const away = 0.18 + (seed >> 3) % 23 / 100;
+    const draw = Math.max(0.05, 1 - home - away);
+    const outcomes = [
+      { kind: "home", teamCode: match.home.code, label: match.home.name, probability: home },
+      { kind: "draw", label: "Draw", probability: draw },
+      { kind: "away", teamCode: match.away.code, label: match.away.name, probability: away }
+    ];
+    const now = this.opts.now ?? options?.now ?? /* @__PURE__ */ new Date();
+    const asOf = new Date(now.getTime() - 6e4).toISOString();
+    return buildMarketSignal({
+      match,
+      source: "fake",
+      sourceMarketId: `fake-${match.id}`,
+      asOf,
+      fetchedAt: now.toISOString(),
+      outcomes,
+      liquidity: 5e4,
+      now,
+      maxAgeMs: options?.maxAgeMs
+    });
+  }
+};
+function hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = h * 31 + s.charCodeAt(i) >>> 0;
+  return h % 1e5;
+}
+
+// src/markets/mapping.2026.json
+var mapping_2026_default = {
+  version: 1,
+  note: "Optional matchId -> Polymarket EVENT-slug OVERRIDES. By default the slug is DERIVED from each fixture (fifwc-{home}-{away}-{UTC-date}, e.g. fifwc-mex-rsa-2026-06-11), so most matches need NO entry here. Add an entry only for a fixture whose real Polymarket slug differs (e.g. a team abbreviation that isn't the FIFA code, or a tz-shifted date). The event payload carries the three moneyline binary markets; each outcome's probability is its 'Yes' price; validation fails closed. Entry: { eventSlug, eventId? }.",
+  markets: {}
+};
+
+// src/markets/polymarket.ts
+var DEFAULT_BASE2 = "https://gamma-api.polymarket.com";
+var ALLOWED_HOSTS = /* @__PURE__ */ new Set(["gamma-api.polymarket.com"]);
+var USER_AGENT2 = "claudinho/0.0 (+https://github.com/arturogarrido/claudinho)";
+var DEFAULT_TIMEOUT_MS = 8e3;
+var WC_SERIES_SLUG = "soccer-fifwc";
+var WC_SPORT = "fifwc";
+var KICKOFF_TOLERANCE_MS = 6 * 60 * 6e4;
+var NON_REGULAR_TIME = /extra time|penalt|to advance|to qualif|win the (group|tournament|cup|title)/i;
+var BUNDLED_MAPPING = mapping_2026_default.markets;
+var PolymarketProvider = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+  }
+  opts;
+  name = "polymarket";
+  async findSignal(match, options) {
+    return (await this.resolveOne(match, options)).signal;
+  }
+  async findSignals(matches, options) {
+    const signals = /* @__PURE__ */ new Map();
+    const checked = /* @__PURE__ */ new Set();
+    const deadline = options?.deadlineMs != null ? Date.now() + options.deadlineMs : Number.POSITIVE_INFINITY;
+    for (const m of matches) {
+      if (Date.now() >= deadline) break;
+      const r = await this.resolveOne(m, options);
+      if (r.checked) checked.add(m.id);
+      if (r.signal) signals.set(m.id, r.signal);
+    }
+    return { signals, checked };
+  }
+  /**
+   * Resolve one match. `checked` distinguishes a DEFINITIVE result (reached the
+   * source and found no usable market, or the fixture is unmappable) from a
+   * provider/network error — so transient failures are retried, not
+   * negative-cached.
+   */
+  async resolveOne(match, options) {
+    const entry = (this.opts.mapping ?? BUNDLED_MAPPING)[match.id];
+    const eventSlug = entry?.eventSlug ?? deriveEventSlug(match);
+    if (!eventSlug) return { checked: true };
+    try {
+      const event = await this.fetchEvent(eventSlug, options?.timeoutMs);
+      const signal = event ? this.toSignal(match, eventSlug, event, options) : void 0;
+      return { signal, checked: true };
+    } catch {
+      return { checked: false };
+    }
+  }
+  async fetchEvent(slug, timeoutMs) {
+    const base = this.opts.baseUrl ?? DEFAULT_BASE2;
+    assertAllowedHost(base);
+    const url = `${base}/events?slug=${encodeURIComponent(slug)}`;
+    const doFetch = this.opts.fetchImpl ?? fetch;
+    const res = await doFetch(url, {
+      signal: AbortSignal.timeout(timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      headers: { Accept: "application/json", "User-Agent": USER_AGENT2 }
+    });
+    if (res.status === 404) return void 0;
+    if (!res.ok) {
+      throw new Error(`Polymarket request failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json();
+    const event = Array.isArray(data) ? data[0] : data;
+    return event && typeof event === "object" ? event : void 0;
+  }
+  toSignal(match, eventSlug, event, options) {
+    if (event.active === false || event.closed === true) return void 0;
+    if (event.seriesSlug != null && event.seriesSlug !== WC_SERIES_SLUG && event.sport?.sport !== WC_SPORT) {
+      return void 0;
+    }
+    if (event.slug != null && event.slug !== eventSlug) return void 0;
+    const start = event.startTime ? Date.parse(event.startTime) : Number.NaN;
+    const kick = Date.parse(match.kickoff);
+    if (Number.isFinite(start) && Number.isFinite(kick) && Math.abs(start - kick) > KICKOFF_TOLERANCE_MS) {
+      return void 0;
+    }
+    const moneyline = (event.markets ?? []).filter(
+      (m) => (m.sportsMarketType ?? "moneyline") === "moneyline"
+    );
+    const homeMarket = pickMarket(moneyline, match.home.code, match.home.name);
+    const awayMarket = pickMarket(moneyline, match.away.code, match.away.name);
+    const drawMarket = pickDraw(moneyline);
+    if (!homeMarket || !awayMarket) return void 0;
+    const legIds = [homeMarket, awayMarket, drawMarket].filter((m) => m != null).map((m) => m.id ?? m.slug ?? "");
+    if (new Set(legIds).size !== legIds.length) return void 0;
+    const legs = [
+      ["home", homeMarket, match.home.code, match.home.name],
+      ["draw", drawMarket, void 0, "Draw"],
+      ["away", awayMarket, match.away.code, match.away.name]
+    ];
+    const outcomes = [];
+    let asOf = event.updatedAt;
+    let liquidity;
+    for (const [kind, market, teamCode, label] of legs) {
+      if (!market) continue;
+      if (market.closed === true || market.active === false) return void 0;
+      if (market.description && NON_REGULAR_TIME.test(market.description)) return void 0;
+      const yes = yesPrice(market);
+      if (yes == null) return void 0;
+      outcomes.push({ kind, teamCode, label, probability: yes });
+      if (market.updatedAt && (!asOf || market.updatedAt < asOf)) asOf = market.updatedAt;
+      const liq = numberish(market.liquidityNum ?? market.liquidity);
+      if (liq != null) liquidity = liquidity == null ? liq : Math.min(liquidity, liq);
+    }
+    const rawSum = outcomes.reduce((s, o) => s + o.probability, 0);
+    if (rawSum < 0.9 || rawSum > 1.15) return void 0;
+    const signal = buildMarketSignal({
+      match,
+      source: "polymarket",
+      sourceMarketId: event.id ?? eventSlug,
+      asOf: asOf ?? (/* @__PURE__ */ new Date()).toISOString(),
+      outcomes,
+      liquidity,
+      now: options?.now ?? this.opts.now,
+      maxAgeMs: options?.maxAgeMs ?? this.opts.maxAgeMs
+    });
+    return signal.ambiguous ? void 0 : signal;
+  }
+};
+function deriveEventSlug(match) {
+  const home = match.home.code.toLowerCase();
+  const away = match.away.code.toLowerCase();
+  if (home === away || home === "tbd" || away === "tbd") return void 0;
+  if (!/^[a-z]{3}$/.test(home) || !/^[a-z]{3}$/.test(away)) return void 0;
+  const date = match.kickoff.slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return void 0;
+  return `fifwc-${home}-${away}-${date}`;
+}
+function slugToken(m) {
+  return (m.slug ?? "").toLowerCase().split("-").pop() ?? "";
+}
+function isDrawMarket(m) {
+  return slugToken(m) === "draw" || (m.groupItemTitle ?? "").trim().toLowerCase().startsWith("draw");
+}
+function pickMarket(markets, teamCode, teamName) {
+  const code = teamCode.toLowerCase();
+  const name = teamName.trim().toLowerCase();
+  const teamMarkets = markets.filter((m) => !isDrawMarket(m));
+  const bySlug = teamMarkets.find((m) => slugToken(m) === code);
+  if (bySlug) return bySlug;
+  return teamMarkets.find((m) => (m.groupItemTitle ?? "").trim().toLowerCase() === name);
+}
+function pickDraw(markets) {
+  return markets.find(isDrawMarket);
+}
+function assertAllowedHost(base) {
+  let host;
+  try {
+    host = new URL(base).host;
+  } catch {
+    throw new Error(`Invalid Polymarket base URL: ${base}`);
+  }
+  if (!ALLOWED_HOSTS.has(host)) {
+    throw new Error(`Polymarket host not allow-listed: ${host}`);
+  }
+}
+function yesPrice(market) {
+  const labels = parseJsonArray(market.outcomes);
+  const prices = parseJsonArray(market.outcomePrices).map((p2) => Number(p2));
+  if (labels.length === 0 || labels.length !== prices.length) return void 0;
+  const i = labels.findIndex((l) => l.trim().toLowerCase() === "yes");
+  if (i < 0) return void 0;
+  const p = prices[i];
+  return typeof p === "number" && Number.isFinite(p) && p > 0 && p <= 1 ? p : void 0;
+}
+function parseJsonArray(v) {
+  if (Array.isArray(v)) return v.map((x) => String(x));
+  if (typeof v === "string") {
+    try {
+      const parsed = JSON.parse(v);
+      return Array.isArray(parsed) ? parsed.map((x) => String(x)) : [];
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+function numberish(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : void 0;
+  if (typeof v === "string") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return void 0;
+}
+
+// src/markets/provider.ts
+function resolveMarketSource(explicit) {
+  if (explicit) return explicit;
+  if (typeof process !== "undefined" && process.env?.CLAUDINHO_MARKETS_SOURCE) {
+    return process.env.CLAUDINHO_MARKETS_SOURCE;
+  }
+  return "polymarket";
+}
+function makeMarketProvider(source) {
+  switch (resolveMarketSource(source)) {
+    case "fake":
+      return new FakeMarketProvider({ synthesize: true });
+    case "none":
+    case "off":
+      return new FakeMarketProvider();
+    // no synth → yields no signals, no network
+    default:
+      return new PolymarketProvider();
+  }
+}
+async function getMarketSignal(provider, match, options) {
+  try {
+    return await provider.findSignal(match, options);
+  } catch {
+    return void 0;
+  }
+}
+async function getMarketSignals(provider, matches, options) {
+  try {
+    return await provider.findSignals(matches, options);
+  } catch {
+    return { signals: /* @__PURE__ */ new Map(), checked: /* @__PURE__ */ new Set() };
+  }
+}
 export {
   DEFAULT_COMPETITION,
   DEFAULT_FLAVOR,
+  DEFAULT_MAX_AGE_MS,
   EspnAdapter,
   FLAVOR_LEVELS,
+  FakeMarketProvider,
+  PolymarketProvider,
   allFixtures,
   asFlavorLevel,
+  buildMarketSignal,
   byKickoff,
   competitionBase,
   computeStandings,
   countdown,
+  deriveFavorite,
+  favoriteStrength,
   fixturesByDate,
   fixturesByGroup,
   fixturesByTeam,
   flagEmoji,
   formatKickoff,
   getLiveMatches,
+  getMarketSignal,
+  getMarketSignals,
   getMatchesForDate,
   groups,
+  hasSaneDistribution,
   isFinished,
   isFlavorLevel,
   isLive,
+  isReliableMarketSignal,
+  isStaleSignal,
   isValidDate,
   isValidTimeZone,
+  liveSourceLabel,
   localDate,
   makeAdapter,
+  makeMarketProvider,
   mapEspnEvent,
+  mapsCleanly,
+  marketAttributionText,
+  marketBlock,
+  marketFavoriteText,
+  marketLine,
+  marketProbabilityText,
+  marketSourceLabel,
   matchFlavor,
   matchLocation,
   mergeLive,
   nationToFlag,
   nationToRegion,
   nextFixtureForTeam,
+  normalizeOutcomes,
   outcomeFromScore,
   resolveCompetition,
+  resolveMarketSource,
   resolveTz,
   scoreline
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@claudinho/core",
-  "version": "0.2.0",
-  "description": "Domain model, data-provider adapters, and helpers for Claudinho — the 2026 football tournament in your dev environment.",
+  "version": "0.3.0",
+  "description": "Domain model, provider adapters, standings, and a read-only market-signal sidecar for Claudinho — the 2026 men's football tournament. Not affiliated with FIFA or Anthropic.",
   "type": "module",
   "license": "MIT",
   "author": "Arturo Garrido",