vyndr/specs/session55-self-learning.md

Spec — Self-Learning Loop (Outcome Tracking + Accuracy) — Session 55

Problem

VYNDR grades props but never checks whether it was right. The intelligence is static — no outcome tracking, no accuracy record, no "the system learns" signal. This is the #1 trust builder for a product a 98K-follower bettor would stake his reputation on: showing real accuracy, including misses.

What we build

outcomeService — settles locked snapshot grades against real game results, records hit/miss per graded prop, and aggregates a rolling accuracy record by grade tier. Powered by the FREE MLB Stats API game log (the same source the grade pipeline already uses); NBA/WNBA degrade to pending when the Python stats service is offline (matches existing posture). Zero new dependency, zero new paid API credits.

Data source

mlbStatsAdapter.getPlayerStats(name) → { found, last10: [{ date, opponent, stat:{…} }] }. A prop is "settled" when a game-log row exists for the graded date (presence in the log ⇒ the game is FINAL). The actual stat value is read via a settlement map (VYNDR stat_type → statsapi game-log field), mirroring MLB_LOG_FIELD.

Settlement logic

For each grade in snapshot:{sport}:latest:

• targetDates = the UTC date and America/New_York date of gradedAt.timestamp (covers late-game ET rollover without heavy TZ math).
• Find the game-log row whose date ∈ targetDates. None ⇒ pending (skip).
• actual = settlement-map value for the graded stat_type. Unmappable ⇒ skip.
• result:
  • side over: actual > line ⇒ hit; actual < line ⇒ miss; == ⇒ push
  • side under: actual < line ⇒ hit; actual > line ⇒ miss; == ⇒ push
• Idempotent: outcome key = nameKey(player)|stat|line|side|date. A prop settles once; re-runs never double-count.

Persistence (Redis, no DB migration)

• outcomes:{sport}:log — array of settled outcomes (newest first, cap 1000, deduped by key). Each: { key, player, stat, line, side, grade, actual, result, date, gradedAt, settledAt }.
• accuracy:{sport} — { sport, updated_at, window_days:30, sample, overall:{hits,total,pushes,pct}, byGrade:{'A+':{…},'A':{…},'B':{…},'C':{…},'D':{…}} }.
• accuracy:overall — same shape aggregated across sports (dashboard header).
• pct = hits / (hits + misses) over the trailing 30 days; pushes excluded from pct.

Endpoints

• GET /api/accuracy (public, cached 5m) → { overall, sports:{mlb,nba,wnba,…}, updated_at }.
• GET /api/ledger/accuracy (public) → { buckets:[{ grade, hits, total, pct }] } (feeds the existing Next proxy web/src/app/api/ledger/accuracy).
• POST /api/internal/outcomes/:sport and /outcomes/all (internal-key gated) — trigger settlement. Same auth as the snapshot trigger.
• Cron: settleAllOutcomes() runs on the snapshot scheduler tick BEFORE grading (settle yesterday's completed games, then grade today's).

Frontend

• Dashboard header accuracy pill: "A-RATED · 68% HIT RATE (30D)" from /api/accuracy. Self-hides when sample is too small (< MIN_SAMPLE).
• GradeResultCard: "A-rated props hit 68% of the time" line when accuracy for that grade tier is available (passed via gradeAdapter).
• Snapshot prop rows: a settled prop shows ✅ HIT (2) / ❌ MISS (1) / PUSH derived from outcomes:{sport}:log (via the snapshot read merge).

Acceptance criteria

1. settleSnapshot('mlb', deps) with injected grades + game logs returns settled outcomes with correct hit/miss/push for over AND under sides.
2. Settlement is idempotent — running twice does not double-count.
3. Accuracy aggregates hits/total/pct by grade tier over the 30-day window.
4. A prop with no matching game-log row stays pending and is excluded.
5. GET /api/accuracy returns the persisted record (empty-safe when cold).
6. NBA/WNBA (offline stats) degrade to pending, never throw.
7. All deps injectable → tests hit zero network.

Test plan

tests/unit/outcomeService.test.js:

• hit/miss/push for over + under; unmappable stat skipped; missing game skipped.
• idempotency (dedupe by key across two runs).
• accuracy bucketing + pct math + 30-day window filter + MIN_SAMPLE gating.
• getAccuracy cold-cache empty shape. tests/integration/accuracy.test.js:
• GET /api/accuracy and GET /api/ledger/accuracy return valid shapes.