@claudinho/core 0.9.2 → 0.9.4

package/dist/index.d.ts

@@ -167,7 +167,11 @@ declare function formatDate(iso: string, opts?: FormatOpts): string;
 declare function formatTime(iso: string, opts?: FormatOpts): string;
 /** Compact human countdown until kickoff: "3d4h", "2h10m", "45m", or "now". */
 declare function countdown(iso: string, from?: Date): string;
-/** The calendar date (YYYY-MM-DD) of a kickoff in the target timezone. */
+/**
+ * The calendar date (YYYY-MM-DD) of a kickoff in the target timezone, or ''
+ * when the input can't be parsed — an unfileable fixture matches no date rather
+ * than throwing out of whatever was grouping by day.
+ */
 declare function localDate(iso: string, tz?: string): string;
 
 /**
@@ -183,36 +187,6 @@ declare function isValidTimeZone(tz: string | undefined | null): boolean;
  */
 declare function isValidDate(s: string | undefined | null): boolean;
 
-/**
- * Feed-string sanitizer — the chokepoint between untrusted provider data and
- * every output surface (terminal, statusline, share cards, and the Claude Code
- * hook, whose stdout lands in the model's context). Strips control characters
- * (C0 incl. ESC, DEL, C1) so a compromised feed can't inject ANSI escapes or
- * multi-line text, and caps length so one field can't flood a surface.
- *
- * Applied at the ESPN adapter boundary (toTeam / mapEspnEvent) and mirrored on
- * the statusline's cache reads (defense against a poisoned cache file).
- */
-
-/** Default per-field cap — generous for any real team/venue name. */
-declare const FEED_TEXT_MAX = 100;
-/**
- * Strip C0/C1 control characters (including ESC) and cap at `max` code points.
- * Whitespace controls (tab/newline/CR) become a single space so words a hostile
- * feed split across lines don't fuse together. Total: never throws.
- */
-declare function sanitizeFeedText(value: string, max?: number): string;
-/**
- * Sanitized, display-safe copy of a Match. Used on cache reads (the
- * statusline/hook render straight from the cache file), so it must be total:
- * a malformed entry yields empty strings, never a throw. Beyond the string
- * fields, the RENDERED numeric fields (score, shootout, minute) are dropped
- * unless they are real finite numbers — poisoned values degrade to "vs" /
- * "LIVE", never to injected text. Shootout never survives without its score
- * (the adapter-level invariant, re-enforced here).
- */
-declare function sanitizeMatchStrings(m: Match): Match;
-
 /**
  * Display-width helpers for monospace/plain-text alignment.
  *
@@ -225,6 +199,15 @@ declare function sanitizeMatchStrings(m: Match): Match;
  */
 /** Terminal display width of a string (grapheme clusters; emoji count as 2). */
 declare function displayWidth(s: string): number;
+/**
+ * Truncate to `maxColumns` display columns, appending `marker` when anything
+ * was dropped. Never splits a grapheme cluster.
+ *
+ * `padVisible` deliberately never truncates, so a single over-wide value pushed
+ * every other column out of line for the whole table — and on the statusline,
+ * whose entire contract is one short line, nothing bounded the result at all.
+ */
+declare function truncateVisible(s: string, maxColumns: number, marker?: string): string;
 /**
  * Pad with trailing spaces to `width` DISPLAY columns (never truncates — a
  * too-long value overflows its column rather than being cut mid-name).
@@ -401,6 +384,31 @@ declare const LIVE_WINDOW_MS: number;
 declare const KNOCKOUT_EXTRA_TIME_MS: number;
 /** Live-window length for a fixture — longer for knockout (extra time + penalties). */
 declare function liveWindowMsFor(m: Match): number;
+/**
+ * True once EVERY bundled fixture's (stage-aware) live window has ELAPSED —
+ * derived from the bundled schedule rather than a hardcoded date (same reasoning
+ * as the derived knockout window: the `CLAUDINHO_COMPETITION` seam must not carry
+ * a dead calendar).
+ *
+ * Named for exactly what it measures. This is a TIME predicate, not proof that
+ * every match was played: the bundled schedule is a **resultless skeleton** (every
+ * fixture ships `SCHEDULED` by design), so status can't inform it — a POSTPONED or
+ * abandoned fixture still reads as elapsed once its window passes. That is
+ * acceptable for the only use it has (turning a spent schedule into a sign-off),
+ * and it's why this is not called `isTournamentComplete`. **Make it status-aware
+ * against the live overlay before reusing it for anything that asserts results.**
+ *
+ * Deliberately a GLOBAL condition, independent of any team filter: an eliminated
+ * team mid-tournament has no next fixture either, and must NOT read as "over".
+ * Every other empty case still fails closed to the neutral `⚽ —`.
+ *
+ * Callers must additionally confirm the bundled schedule even applies — it
+ * describes the DEFAULT competition, so `CLAUDINHO_COMPETITION` pointing elsewhere
+ * makes this answer meaningless (see the `DEFAULT_COMPETITION` gates in the CLI).
+ *
+ * Empty fixture list → false: "we know nothing" is not "it's over".
+ */
+declare function isTournamentWindowOver(now?: number, fixtures?: Match[]): boolean;
 /** Fixtures whose (stage-aware) live window contains `now` (cheap, static — no network). */
 declare function fixturesInLiveWindow(now?: number, fixtures?: Match[]): Match[];
 /**
@@ -484,6 +492,17 @@ interface ProviderCapabilities {
 interface ProviderAdapter {
     readonly name: string;
     readonly capabilities: ProviderCapabilities;
+    /**
+     * Expected group-table scope for omission checks. Omit when the competition's
+     * full group set is not known in advance.
+     */
+    readonly expectedStandingsGroups?: readonly string[];
+    /**
+     * Groups whose degraded roster may be derived from the bundled schedule.
+     * This is deliberately separate from expected scope: a custom competition
+     * can have known groups without sharing the bundled World Cup teams.
+     */
+    readonly standingsFallbackGroups?: readonly string[];
     /** All fixtures/results for a single calendar date (provider's timezone semantics). */
     fetchByDate(dateISO: string): Promise<Match[]>;
     /** Currently in-progress matches (poll path). */
@@ -493,8 +512,9 @@ interface ProviderAdapter {
     /**
      * Optional authoritative group tables (cumulative across the group stage).
      * Returned in standings order per group. Providers that can't supply a real
-     * table omit this; callers then fall back (degraded) to a roster at zero —
-     * never a wrong, partial table computed from a narrow live window.
+     * table omit this; callers then fail closed (degraded), using a roster at zero
+     * only when `standingsFallbackGroups` declares bundled-schedule compatibility
+     * — never a wrong, partial table computed from a narrow live window.
      */
     fetchStandings?(): Promise<GroupStandings[]>;
     /** Optional push subscription (websocket/SSE providers). Returns an unsubscribe fn. */
@@ -513,6 +533,118 @@ interface ProviderAdapter {
     };
 }
 
+/**
+ * Bounded collections — the type that carries its own honesty.
+ *
+ * Every round of review found a list that was capped without saying so, or that
+ * reported a post-cap count as the total, or that said "none found" when it had
+ * simply run out of budget. Those are the same bug three ways: the shape of the
+ * data did not carry what the reader needed to interpret it. A `BoundedList`
+ * cannot be constructed without stating all four facts.
+ */
+interface BoundedList<T> {
+    /** What survived the cap. */
+    readonly items: readonly T[];
+    /**
+     * How many were established before capping. Exact when `complete` is true;
+     * otherwise it may only be a lower bound over the records examined.
+     */
+    readonly total: number;
+    /** `items.length` — kept explicit so a serialized payload is self-describing. */
+    readonly shown: number;
+    /** Did the cap drop anything? */
+    readonly truncated: boolean;
+    /**
+     * Did we finish looking? False when a deadline, error, or partial fetch cut
+     * the work short — so a caller can tell "there are none" from "we don't know".
+     * An empty list with `complete: false` must NEVER render as "nothing found".
+     */
+    readonly complete: boolean;
+}
+/**
+ * Bound a list, recording what that cost.
+ *
+ * SLICE BEFORE MAP is the caller's job — this records the outcome, it does not
+ * make an unbounded traversal safe. `takeBounded` is the one that bounds work.
+ */
+declare function bounded<T>(items: readonly T[], max: number, complete?: boolean): BoundedList<T>;
+
+/**
+ * The vocabulary for "we could not use this".
+ *
+ * `undefined` was doing five jobs at once — absent, malformed, ambiguous, timed
+ * out, and definitively none — and the caller could not tell them apart. That
+ * ambiguity is what let a schema failure get negative-cached as the FACT "this
+ * fixture has no market", and what made `checked` mean two different things on
+ * two paths. Every rejection now says which kind it is.
+ */
+/** A value we produced, or the reason we did not. */
+type ParseResult<T> = {
+    readonly kind: 'valid';
+    readonly value: T;
+}
+/** We read the payload fine, and the answer is genuinely "nothing here". Cacheable. */
+ | {
+    readonly kind: 'definitive-none';
+    readonly reason: string;
+}
+/** We could not read the payload. A fact about US, not about the fixture. NOT cacheable. */
+ | {
+    readonly kind: 'malformed';
+    readonly reason: string;
+}
+/**
+ * The payload admits more than one reading. Never guess between them.
+ *
+ * CACHEABLE, unlike the two below. This is a fact about a payload we read
+ * successfully — two legs claiming the same team, an incoherent 1X2 — and it
+ * is STABLE: fetching again returns the same bytes and the same ambiguity.
+ * Treating it as non-cacheable meant re-fetching on every single command,
+ * forever, and under the default-on enrichment deadline those doomed fixtures
+ * consumed the whole budget and starved the resolvable ones behind them.
+ * A negative TTL is a bounded delay if the provider later fixes their data;
+ * a permanent refetch loop is not bounded by anything.
+ */
+ | {
+    readonly kind: 'ambiguous';
+    readonly reason: string;
+}
+/**
+ * We never reached a verdict — the deadline expired, the budget ran out.
+ * A fact about the CLOCK, not about the fixture. NOT cacheable.
+ *
+ * This kind exists because the alternative was folding a timeout into
+ * `malformed`, which is the same conflation this type was written to end.
+ */
+ | {
+    readonly kind: 'unresolved';
+    readonly reason: string;
+};
+declare const valid: <T>(value: T) => ParseResult<T>;
+declare const definitiveNone: <T>(reason: string) => ParseResult<T>;
+declare const malformed: <T>(reason: string) => ParseResult<T>;
+declare const ambiguous: <T>(reason: string) => ParseResult<T>;
+declare const unresolved: <T>(reason: string) => ParseResult<T>;
+/** The value, or undefined — for callers that genuinely do not care why. */
+declare function parsedValue<T>(r: ParseResult<T>): T | undefined;
+/**
+ * May this rejection be remembered for the length of a TTL?
+ *
+ * The line is whether we READ the payload, not whether we liked it. A
+ * definitive none and an ambiguity are both conclusions drawn from bytes we
+ * understood, and both are stable across a refetch — so remembering them is
+ * correct, and re-asking immediately just burns the request.
+ *
+ * `malformed` and `unresolved` are facts about US: a shape we could not read
+ * (which may be a provider mid-deploy) and a clock that ran out. Remembering
+ * either would suppress the retry that recovers.
+ */
+declare function isCacheable<T>(r: ParseResult<T>): boolean;
+
+interface MapContext {
+    groupByTeam?: Record<string, string>;
+}
+
 /**
  * ESPN adapter — the free, keyless default/fallback source.
  *
@@ -542,70 +674,21 @@ declare class ProviderError extends Error {
     /** 429/403 — the upstream is refusing us; retrying at the live cadence makes it worse. */
     get throttled(): boolean;
 }
-interface EspnStatusType {
-    name?: string;
-    state?: string;
-    completed?: boolean;
-    shortDetail?: string;
-}
-interface EspnStatus {
-    type?: EspnStatusType;
-    clock?: number;
-    displayClock?: string;
-    period?: number;
-}
-interface EspnTeam {
-    abbreviation?: string;
-    displayName?: string;
-    shortDisplayName?: string;
-    name?: string;
-    location?: string;
-}
-interface EspnCompetitor {
-    homeAway?: 'home' | 'away';
-    score?: string;
-    /** Penalty-shootout tally, present only on shootout matches (ESPN sends a number). */
-    shootoutScore?: number | string;
-    winner?: boolean;
-    team?: EspnTeam;
-}
-interface EspnCompetition {
-    id?: string;
-    date?: string;
-    competitors?: EspnCompetitor[];
-    venue?: {
-        fullName?: string;
-        address?: {
-            city?: string;
-            country?: string;
-        };
-    };
-    status?: EspnStatus;
-}
-interface EspnSeason {
-    year?: number;
-    slug?: string;
-}
-interface EspnEvent {
-    id: string;
-    date: string;
-    name?: string;
-    shortName?: string;
-    season?: EspnSeason;
-    status?: EspnStatus;
-    competitions?: EspnCompetition[];
-}
-/** Optional context to enrich mapping (authoritative team->group letter). */
-interface MapContext {
-    /** Map of UPPERCASE team code -> group letter ("A".."L"), from standings. */
-    groupByTeam?: Record<string, string>;
-}
 /** Map a single ESPN event into the canonical Match model. Exported for tests. */
-declare function mapEspnEvent(ev: EspnEvent, ctx?: MapContext): Match;
+declare function mapEspnEvent(ev: unknown, ctx?: MapContext): Match | undefined;
+/** Project an ESPN standings payload onto group tables. Exported for tests. */
+declare function parseStandings(data: unknown): GroupStandings[];
 interface EspnAdapterOptions {
     baseUrl?: string;
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
+    /**
+     * Expected standings groups for completeness checks and definitive group
+     * validation. Defaults to the bundled groups for the default World Cup base;
+     * custom bases leave the scope open unless supplied. Declaring custom groups
+     * does not authorize use of the bundled World Cup roster on failure.
+     */
+    expectedStandingsGroups?: readonly string[];
     /**
      * Enrich group-stage matches with their group letter via the standings
      * endpoint (one extra request). Default true. Set false on the hot live-poll
@@ -613,39 +696,13 @@ interface EspnAdapterOptions {
      */
     enrichGroups?: boolean;
 }
-interface EspnStandingsStat {
-    name?: string;
-    value?: number;
-}
-interface EspnStandingsEntry {
-    team?: EspnTeam;
-    stats?: EspnStandingsStat[];
-}
-interface EspnStandingsChild {
-    name?: string;
-    abbreviation?: string;
-    standings?: {
-        entries?: EspnStandingsEntry[];
-    };
-}
-interface EspnStandings {
-    children?: EspnStandingsChild[];
-}
-/**
- * Parse the standings payload into group tables. Pure (exported for tests).
- *
- * Two non-obvious robustness points, both verified against the live response:
- *  - ESPN's `entries` array is NOT in rank order, so we sort by the `rank` stat
- *    (falling back to points → GD → GF → code when rank is absent).
- *  - Non-group `children` (knockout brackets) are skipped by the "Group X" name
- *    test, so this stays correct once the bracket phase begins.
- */
-declare function parseStandings(data: EspnStandings): GroupStandings[];
 declare class EspnAdapter implements ProviderAdapter {
     private readonly opts;
     readonly name = "espn";
     readonly capabilities: ProviderCapabilities;
-    /** Cached team-code -> group-letter map (built lazily from standings). */
+    readonly expectedStandingsGroups?: readonly string[];
+    readonly standingsFallbackGroups?: readonly string[];
+    /** Short-lived team-code -> group-letter map (built lazily from standings). */
     private groupMap?;
     /**
      * One in-flight/recent standings fetch shared by fetchStandings and
@@ -677,15 +734,17 @@ declare class EspnAdapter implements ProviderAdapter {
     private sharedStandings;
     /**
      * Authoritative, cumulative group tables from the standings endpoint. Throws
-     * on fetch/parse failure (the caller decides the fallback). Group-stage only:
-     * non-group `children` are filtered out by {@link parseStandings}.
+     * on fetch failure. Group-stage only: non-group `children` are filtered out
+     * by {@link parseStandings}; malformed rows are omitted without hiding their
+     * readable siblings.
      */
     fetchStandings(): Promise<GroupStandings[]>;
     /**
-     * Build (and cache) a team-code -> group-letter map from the standings
+     * Build (and briefly cache) a team-code -> group-letter map from the standings
      * endpoint. Best-effort: returns {} if standings are unavailable — but a
-     * transient failure is NOT cached (only a successful parse pins the map), so
-     * one blip can't silently drop group letters for the adapter's lifetime.
+     * transient failure is NOT cached, and a partial successful parse expires at
+     * the standings TTL, so neither can silently drop group letters for the
+     * adapter's lifetime.
      * Reuses the same parse/fetch as {@link fetchStandings}, so the two never
      * drift and one command never fetches standings twice.
      */
@@ -737,22 +796,33 @@ declare function getMatchesForDate(adapter: ProviderAdapter, dateISO: string): P
 interface StandingsResult {
     /** Group tables in group-letter order; each table's rows in standings order. */
     tables: GroupStandings[];
-    /** True when no authoritative table was available and rows are a static roster. */
+    /** True when no authoritative table was available; tables may be a static roster or empty. */
     degraded: boolean;
-    /** The provider that served a real table (absent when degraded). */
+    /** Provider that served the authoritative result, including an empty one (absent when degraded). */
     source?: string;
 }
 /**
  * Authoritative group tables, preferring the provider's cumulative standings and
- * FAILING CLOSED to a roster-at-zero (degraded) when none is available.
+ * FAILING CLOSED when none is available. An adapter with explicit bundled-
+ * roster compatibility may use the roster-at-zero; otherwise it returns an
+ * empty degraded result because expected group letters alone do not prove the
+ * bundle belongs to the same competition.
  *
  * Deliberately does NOT compute a table from a live-match window: that silently
  * drops earlier matchdays and reports a wrong, partial table (e.g. all-zeros for
  * a group not playing today) — the bug this replaced. A degraded roster is
- * honestly empty; a confidently-wrong table is the failure mode we refuse.
+ * explicitly zeroed; a confidently-wrong table is the failure mode we refuse.
  *
- * An empty `tables` with `degraded: false` means the fetch succeeded but the
- * asked-for group isn't in it (caller renders "no such group").
+ * An empty `tables` with `degraded: false` means either the fetch succeeded but
+ * the asked-for group wasn't in it, or the group is definitively outside the
+ * adapter's declared scope (caller renders "no such group"). A group declared
+ * in that expected scope but omitted from a partial
+ * provider result takes the degraded fallback instead of rendering as an
+ * authoritative empty table. An aggregate read also falls back when any group
+ * in that scope is absent; one result-level verdict cannot honestly describe a
+ * mix of live tables and static roster tables. Transport failure without
+ * explicit bundled-roster compatibility stays empty and degraded; it must
+ * never borrow the bundled World Cup roster.
  */
 declare function getStandings(adapter: ProviderAdapter, group?: string): Promise<StandingsResult>;
 declare function knockoutWindow(): {
@@ -856,15 +926,65 @@ declare function getMatchById(adapter: ProviderAdapter, id: string): Promise<Mat
 declare function getLiveMatches(adapter: ProviderAdapter, now?: Date): Promise<LiveResult>;
 
 /**
- * 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.
+ * Choosing one of several, and reporting on a batch.
+ *
+ * Two shapes, both replacing a boolean that was carrying more meaning than a
+ * boolean can hold.
+ *
+ * `Selection` replaces "the selector returned undefined". Finding no market for
+ * a team and finding TWO markets for that team both produced `undefined`, and
+ * the caller — having no way to tell them apart — recorded the second as the
+ * definitive fact "this fixture has no market" and negative-cached it for the
+ * whole TTL. An ambiguity is the one thing we must never resolve by guessing,
+ * and it was the case being guessed at.
+ *
+ * `BatchResolution` replaces `checked: Set<string>`. That set was maintained
+ * alongside the results rather than derived from them, so "did we reach a
+ * verdict?" and "what was the verdict?" could disagree — and did, on two paths.
+ * Here the verdict IS the record, and cacheability is read off it.
+ */
+
+/** Exactly one, none, or more than one — never "one of the several". */
+type Selection<T> = {
+    readonly kind: 'one';
+    readonly value: T;
+} | {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'ambiguous';
+    readonly count: number;
+};
+/**
+ * The single candidate, or an honest account of why there isn't one.
  *
- * Read-only by design: providers fetch public market data only — no wallet,
- * no auth, no order placement. Nothing here models trading.
+ * Deliberately NOT `candidates[0]`: which of two legs claiming the same team is
+ * the real one is not a question the payload answers, so it is not a question
+ * this function answers either.
  */
+declare function selectOne<T>(candidates: readonly T[]): Selection<T>;
+/**
+ * Every input's verdict, plus whether every input GOT one.
+ *
+ * `complete: false` means the batch was cut short (deadline, provider error) —
+ * the missing entries are unasked questions, not negative answers.
+ */
+interface BatchResolution<T> {
+    readonly results: ReadonlyMap<string, ParseResult<T>>;
+    readonly complete: boolean;
+}
+/** The values that resolved, keyed as they went in. */
+declare function resolvedValues<T>(batch: BatchResolution<T>): Map<string, T>;
+/**
+ * The keys whose verdict may be remembered — see {@link isCacheable}.
+ *
+ * This is the old `checked` set, now DERIVED from each verdict instead of
+ * tracked beside it. A malformed or unresolved key is absent, so a shape we
+ * could not read and a deadline that expired are both retried next time rather
+ * than cached as the fact that this fixture has no market.
+ */
+declare function cacheableKeys<T>(batch: BatchResolution<T>): Set<string>;
+/** An empty batch that reached nobody — what a total provider failure returns. */
+declare function emptyBatch<T>(): BatchResolution<T>;
 
 /** Which match result a priced line refers to (home win / draw / away win). */
 type MarketOutcomeKind = 'home' | 'draw' | 'away' | 'other';
@@ -937,16 +1057,16 @@ interface MarketSignalOptions {
     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.
+ * Result of a batch lookup: every match id's VERDICT, plus whether the batch
+ * finished. Read the signals with `resolvedValues` and the negative-cacheable
+ * ids with `cacheableKeys`.
+ *
+ * This replaces a `checked: Set<string>` that was maintained beside the results
+ * instead of derived from them — so an ambiguous or unreadable payload could be
+ * recorded as the definitive fact "this fixture has no market", suppressing the
+ * refetch for the whole TTL.
  */
-interface MarketSignalsResult {
-    signals: Map<string, MarketSignal>;
-    checked: Set<string>;
-}
+type MarketSignalsResult = BatchResolution<MarketSignal>;
 /**
  * A prediction-market provider. A *separate* swap-point from ProviderAdapter
  * (which supplies match data): different cadence, reliability, and legal
@@ -956,8 +1076,8 @@ 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>;
+    /** Batch form; a verdict per match id (see MarketSignalsResult). */
+    findSignals(matches: readonly Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
 }
 
 /** Default freshness window: a signal older than this is stale (15 minutes). */
@@ -1001,7 +1121,13 @@ declare function mapsCleanly(match: Match, outcomes: MarketOutcome[]): boolean;
 declare function marketSignalRendersFor(match: Match, signal: MarketSignal): 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. */
+/**
+ * Is the signal outside the freshness window? Unparseable timestamps are stale.
+ *
+ * A FUTURE `asOf` is stale too. Freshness was a one-sided test (`now - asOf >
+ * maxAge`), so a timestamp dated forward was never stale and never expired —
+ * failing open permanently, in the direction that looks most trustworthy.
+ */
 declare function isStaleSignal(signal: MarketSignal, options?: MarketSignalOptions): boolean;
 /**
  * The load-bearing gate. A signal is reliable only when it is unambiguous, has
@@ -1077,8 +1203,8 @@ declare function resolveMarketSource(explicit?: string): string;
 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>;
+/** Batch fetch; never throws — an empty, INCOMPLETE batch on any error. */
+declare function getMarketSignals(provider: MarketProvider, matches: readonly Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
 
 /**
  * A network-free MarketProvider for tests and local UX validation. Returns
@@ -1100,10 +1226,130 @@ declare class FakeMarketProvider implements MarketProvider {
     readonly name = "fake";
     constructor(opts?: FakeMarketProviderOptions);
     findSignal(match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
-    findSignals(matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
+    findSignals(matches: readonly Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
     private synthesize;
 }
 
+/** Display columns a label may occupy. Generous for any real team or venue name. */
+declare const MAX_LABEL_COLUMNS = 100;
+/**
+ * Prose meant for a human: a team name, a venue, a city, a market outcome label.
+ *
+ * NFC-normalized so the same name has one representation, bounded on input
+ * length (work), display columns (layout) and code points (bytes), and free of
+ * anything invisible. Whitespace controls fold to a space so words a hostile
+ * feed split across lines cannot fuse.
+ *
+ * Total: never throws, whatever the input.
+ */
+declare function humanLabel(value: unknown, maxColumns?: number): string;
+/**
+ * A flag, GENERATED from the bundled map — never accepted from anywhere.
+ *
+ * This is the load-bearing line of the whole module. Because a flag is produced
+ * here rather than passed through, no untrusted input ever needs to carry an
+ * emoji, so {@link humanLabel} can refuse every invisible code point without
+ * exception. The three P1s that each rode the old emoji exemption (TAG
+ * sequences, variation selectors, ZWJ chains) are not defended against — they
+ * have nowhere to enter.
+ */
+declare function productFlag(nameOrCode: string | undefined): string;
+
+/**
+ * The single place a `Match` is sealed — whichever path it arrived by.
+ *
+ * This closes the PATH asymmetry. A fixture reaches a renderer two ways: live
+ * from the ESPN adapter, or read back from the local cache file that the
+ * statusline and hook render on every prompt. Those two paths had SEPARATE
+ * rules, so every fix landed on one of them:
+ *
+ *   - the live path DERIVED each team's flag from the nation; the cache path
+ *     accepted whatever string sat in `flag`, which is why the emoji exemption
+ *     existed at all and why TAG, variation selectors and ZWJ each produced a P1
+ *   - the live path required `status !== 'SCHEDULED'` before keeping a score;
+ *     the cache path kept any numeric pair, so an edited cache file could show
+ *     a scoreline on a fixture that has not kicked off
+ *   - the live path set `winnerCode` to one of the two competitors by
+ *     construction; the cache path passed any string through, and `winnerCode`
+ *     is what advances a team through the bracket
+ *
+ * Both paths now end HERE, so a rule cannot be added to one and forgotten on the
+ * other. `parseEspnEvent` assembles candidate parts from the feed and seals
+ * them; `parseCachedMatch` seals the record it read. The parity property in
+ * trust-parity.test.ts asserts the two agree, and idempotence — sealing an
+ * already-sealed Match returns it unchanged — is what makes the round trip safe.
+ */
+
+/** Loosely-typed candidate fields — whatever the feed or the cache file held. */
+interface MatchParts {
+    id?: unknown;
+    stage?: unknown;
+    group?: unknown;
+    kickoff?: unknown;
+    venue?: unknown;
+    city?: unknown;
+    country?: unknown;
+    home?: unknown;
+    away?: unknown;
+    score?: unknown;
+    shootout?: unknown;
+    minute?: unknown;
+    status?: unknown;
+    winnerCode?: unknown;
+    updatedAt?: unknown;
+    events?: unknown;
+}
+/**
+ * Validate candidate parts into a Match, or say why not.
+ *
+ * `id`, `kickoff`, `stage` and `status` DROP the whole fixture rather than
+ * falling back to a default. Each decides what the reader is told — status picks
+ * between "FT" and a live scoreline, kickoff decides which calendar day the
+ * fixture is filed under — so substituting a plausible value would invent the
+ * very fact the bad field destroyed.
+ */
+interface SealOptions {
+    /**
+     * Seal in-match events too. Default true.
+     *
+     * The statusline and hook render a scoreline, not a timeline — they never
+     * read `events` — and sealing them is the DOMINANT cost on a 150ms path: a
+     * poisoned cache of 64 live matches carrying 128 events each measured
+     * 11.9 s, because each event's `player` is a label and a label is segmented
+     * grapheme by grapheme. Bounding the COUNT was not enough when the surface
+     * needs ZERO. Cheapest work is work not done.
+     */
+    readonly events?: boolean;
+}
+declare function sealMatch(parts: MatchParts, opts?: SealOptions): ParseResult<Match>;
+/**
+ * A Match read back from our own cache file.
+ *
+ * The cache is a local file the statusline renders on every prompt, so it is
+ * untrusted input in exactly the way a feed response is — with the extra twist
+ * that it holds values we ourselves wrote, which is what made it tempting to
+ * trust. It goes through the same seal.
+ */
+declare function parseCachedMatch(raw: unknown, opts?: SealOptions): ParseResult<Match>;
+/** Cached fixtures, bounded BEFORE the per-record work. */
+declare function parseCachedMatches(raw: unknown, max: number, opts?: SealOptions): BoundedList<Match>;
+
+/**
+ * Validate a market signal, or say why not.
+ *
+ * `matchId` drops the whole signal: it is the key everything else is bound to,
+ * and a signal that cannot name its fixture cannot be checked against one.
+ */
+declare function sealMarketSignal(raw: unknown, options?: {
+    now?: Date;
+    maxAgeMs?: number;
+}): ParseResult<MarketSignal>;
+/** A signal read back from our own cache file — same seal as the live one. */
+declare function parseCachedMarketSignal(raw: unknown, options?: {
+    now?: Date;
+    maxAgeMs?: number;
+}): ParseResult<MarketSignal>;
+
 /**
  * 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
@@ -1131,12 +1377,18 @@ declare class PolymarketProvider implements MarketProvider {
     readonly name = "polymarket";
     constructor(opts?: PolymarketProviderOptions);
     findSignal(match: Match, options?: MarketSignalOptions): Promise<MarketSignal | undefined>;
-    findSignals(matches: Match[], options?: MarketSignalOptions): Promise<MarketSignalsResult>;
+    findSignals(matches: readonly Match[], options?: MarketSignalOptions): Promise<BatchResolution<MarketSignal>>;
     /**
-     * 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.
+     * Resolve one match into a verdict.
+     *
+     * Every exit says which KIND of non-answer it is, because that decides
+     * whether it may be remembered — see `isCacheable`: a conclusion we drew from
+     * a payload we READ is cacheable (including an ambiguity, which is stable),
+     * while a shape we could not read is not. Previously a single
+     * `checked: boolean` collapsed five distinct situations into two, and the
+     * ones that landed on the wrong side of it — an ambiguous payload, a
+     * two-legged market, an incoherent 1X2 — were negative-cached as the fact
+     * that this fixture has no market.
      */
     private resolveOne;
     private fetchEvent;
@@ -1166,12 +1418,15 @@ interface ShareSnippetInput {
     /** Pre-resolved, English title line, e.g. "Next up for Mexico". */
     title: string;
     /** Matches to render (0..n). An empty set still yields a valid titled card. */
-    matches: Match[];
+    /** Read-only: callers pass a bounded view, which must not be mutated. */
+    matches: readonly Match[];
     /**
      * Reliable, display-ready market signals keyed by match id (sidecar — never
      * embedded in Match). Callers gate these; the formatter only renders.
      */
     marketSignals?: Map<string, MarketSignal>;
+    /** False when market enrichment stopped before every relevant match was checked. */
+    marketComplete?: boolean;
     /** Live-data provider name (e.g. "espn") for attribution; omit when static/degraded. */
     source?: string;
     /**
@@ -1202,9 +1457,9 @@ interface ShareSnippetInput {
 declare function formatShareSnippet(input: ShareSnippetInput, options?: ShareSnippetOptions): string;
 interface ShareTableInput {
     /** Group tables to render (1..n); each in standings order. */
-    tables: {
+    tables: readonly {
         group: string;
-        rows: StandingRow[];
+        rows: readonly StandingRow[];
     }[];
     /** Live-data provider name for attribution; omit when degraded/static. */
     source?: string;
@@ -1213,10 +1468,10 @@ interface ShareTableInput {
     /** Body line when there are no tables (e.g. "No group Z."). */
     emptyNote?: string;
     /**
-     * True when the rows are a static roster (no live results), not an
-     * authoritative table. A shared card is pasted into public/social, so this
-     * MUST be surfaced — otherwise a roster-at-zero reads as a real "nobody has
-     * played yet" table. The card then carries an explicit not-live notice.
+     * True when no authoritative table was available. Non-empty rows are a
+     * static roster, not live results; an empty open-scope outage is described by
+     * `emptyNote`. A shared card is pasted into public/social, so degraded state
+     * MUST be surfaced rather than reading as an authoritative table.
      */
     degraded?: boolean;
 }
@@ -1293,4 +1548,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 BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketTopology, type BracketView, type BuildSignalInput, DEFAULT_COMPETITION, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, EspnAdapter, type EspnAdapterOptions, FEED_TEXT_MAX, 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, 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, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, type ResolvedParticipant, SHARE_DISCLAIMER, SHARE_HASHTAG, 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, asFlavorLevel, buildBracketTopology, buildBracketView, buildMarketSignal, byKickoff, competitionBase, computeStandings, countdown, currentOrNextFixtureForTeam, deriveFavorite, displayWidth, 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, isFinished, isFlavorLevel, isLive, isReliableMarketSignal, isResolvedNation, isStaleSignal, isValidDate, isValidTimeZone, knockoutWindow, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookupTeam, makeAdapter, makeMarketProvider, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketSignalRendersFor, marketSourceLabel, matchFlavor, matchKey, matchLocation, mergeLive, nationToFlag, nationToRegion, nextFixtureForTeam, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseStandings, parseTeamSlot, resolveCompetition, resolveMarketSource, resolveTz, sanitizeBundledFixture, sanitizeFeedText, sanitizeMatchStrings, scoreline, stageLabel, stageLabelI18n, t };
+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, 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, 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 };