vyndr/specs/LIVE-TRACKING.md

VYNDR — LIVE TRACKING v1.0 (A1 board, Session 11)

The read is locked pre-game. The game is watched. GRADES NEVER CHANGE IN-GAME — this layer is TRACKING, labeled as such, per the Ledger ethos.

PRINCIPLES

1. Zero out-of-pocket. Free feeds only: statsapi.mlb.com (MLB live boxscore) and the ESPN site API (WNBA summary boxscore). No new dependency, no quota key.
2. Grades never change in-game. The locked pre-game read is untouched; live-progress marks are proto-outcomes rendered in the OUTCOME slot region (ROW-GRAMMAR §2 slot 6). Every live card carries the label "TRACKING — read locked pre-game" exactly once.
3. One meaning per color. Green = on-pace or already-cleared; amber = needs-more / caution; red stays reserved for settled-negative truth (miss / DEAD from NOT-IN-LINEUP). An in-progress prop is NEVER red.
4. Only real box-line values. A player not yet in the box score is ABSENT (no mark, no bar, no zero). Number(null) === 0 is the classic fabrication bug — every numeric path uses strict null guards.
5. An under is never "hit" until final. Under semantics are HOLDS-IF: green HOLDING while the count sits under the line, amber LINE PASSED once the count reaches/passes it (counting stats can still be re-scored; nothing settles until the game is final — the settle pass owns the truth).
6. DEAD is not declared here. An over that "can no longer hit" is only honestly declarable for NOT-IN-LINEUP (S5, already shipped). Live tracking tracks until final; it never over-claims.

DATA SOURCES (real shapes captured live, 2026-07-11)

• MLB — GET statsapi.mlb.com/api/v1/schedule?sportId=1&date=YYYY-MM-DD&hydrate=linescore identifies Live games (status.abstractGameState === 'Live') AND carries the per-game linescore (currentInning / inningState / scheduledInnings) in the same call. Per live game: GET /api/v1/game/{gamePk}/boxscore → teams.{home,away}.players.ID{personId}.stats.{batting,pitching}. A player who hasn't appeared has EMPTY stats objects → absent.
• WNBA — ESPN scoreboard (already cached by scheduleService) identifies in-progress events (status.type.state === 'in', status.period). Per live event: GET site.api.espn.com/.../wnba/summary?event={id} → boxscore.players[].statistics[0] with parallel keys + per-athlete stats string arrays. didNotPlay / empty stats → absent.

STAT MAPS

• MLB (LOCAL map, LIVE_BOX_FIELD) — mirrors the idea of outcomeService.MLB_LOG_FIELD but is deliberately LOCAL: the live boxscore splits batting vs pitching into separate stat objects (the game log picks ONE group by position), and innings_pitched must be parsed in thirds ('5.2' = 5⅔ = 5.667) for live pace math. Wired stats: hits, total_bases, home_runs, rbi, runs, stolen_bases, doubles, walks (batting); strikeouts, earned_runs, innings_pitched, outs, hits_allowed (pitching).
• WNBA (WNBA_BOX_KEY) — points, rebounds, assists, steals, blocks, turnovers, threes (made, parsed from "M-A"), pra (points+rebounds+assists, computed only when all three components are present).

PROP STATE (pure math, web/src/lib/liveProgress.js)

propState({ side, line, current, progress }) →

• over, current > line → hit (✓ HIT — the over has already cleared; a counting stat cannot un-clear; still labeled TRACKING until the settle pass)
• over, not cleared → needs N = floor(line) + 1 − current (beats a push on integer lines); on_pace (green) when current / progress ≥ floor(line)+1, else needs (amber, "NEEDS N")
• under, current < line → holding (green HOLDS chip — never ✓ until final)
• under, current ≥ line → past (amber LINE PASSED — not red; nothing settled)
• current == null → NO state (absent beats wrong) Progress fraction: MLB (inning − (top ? 1 : 0.5)) / scheduledInnings; WNBA (period − 0.5) / 4, clamped to [0, 1].

ENDPOINTS

• GET /api/live/:sport (public, rate-limited 60/min, mounted in app.js) → { sport, date, hasLive, updated_at, games: [{ id, home, away, progress: { label, fraction, inning|period, half }, players: { [nameKey]: { name, values: { stat_type: number } } } }] }. mlb + wnba only; other sports → { hasLive: false, games: [] }.
• POLLING RULE: the route reads live:{sport}:{date} (TTL 90s). On a cache MISS it consults the day's schedule; ONLY when the schedule shows live games does it fetch boxscores. Quota math: 1 schedule call + N boxscore calls per 90s window across ALL users (shared cache), during live windows only — zero boxscore calls when nothing is live.
• Next proxy web/src/app/api/live/[sport]/route.ts (S25 rule — Express is not browser-reachable).

FRONTEND (LIVE SLATE MODE)

• Slate polls /api/live/{sport} every 60s ONLY while live games are on screen (mlb/wnba, status 'in').
• liveProgress.attachLiveProgress(strips, liveIndex) (pure) joins built player strips to live values by nameKey + canonical statType; only graded, unsettled, non-dead props get prop.live.
• StatStrip renders the live mark in the OUTCOME slot region: 1/2 TB · ▲6th + a small game-progress bar + the state chip (ON PACE green / NEEDS 2 amber / HIT ✓ green filled / HOLDS green / LINE PASSED amber). Actions (parlay +, BOOK IT) are suppressed on live props — the pre-game market for the locked line is closed.
• Live games with tracked props float to the top of the slate, ordered by proximity-to-hit (max over-fraction current / needed-total).
• The card label "TRACKING — read locked pre-game" renders once per live card.

ACCEPTANCE CRITERIA

1. Parsers reproduce per-player values from REAL captured feed fixtures; a player absent from the box yields NO entry (never 0).
2. propState covers: over cleared / on-pace / needs-N / under-holds / under-passed / absent — unit-tested.
3. /api/live/:sport cache behavior: hit → no fetch; miss + live games → boxscore fetch + cache write; miss + no live games → schedule check only.
4. attachLiveProgress joins strips ↔ live index and never touches settled, dead, or ungraded props.
5. Full jest suite green from the worktree; cd web && npm run build exit 0.
6. If a game is genuinely live during the build, the service runs once against the real feed and the report shows a real tracked line.

TEST PLAN

• tests/unit/liveTrackingService.test.js — MLB boxscore/linescore + WNBA summary parsers on real-shape fixtures; stat resolution incl. IP thirds; absent-player semantics; live-game identification from schedules.
• tests/unit/liveProgress.test.js — propState math table; progress fractions; attachLiveProgress; proximity sort.
• tests/integration/liveRoute.test.js — cache hit / miss+live / miss+idle / unknown sport, with injected deps (zero network).

— LIVE-TRACKING v1.0 · July 2026 —