Session 55: Self-learning loop + real-time layer (2274 tests)

Product overhaul core — the two transformative, differentiated systems:

Self-learning loop (Phase 2): outcomeService settles locked snapshot grades
against real MLB Stats API results → hit/miss/push, rolling accuracy by grade
tier (30d window). Idempotent, injectable, unit-tested. New GET /api/accuracy +
/api/ledger/accuracy + internal settle triggers + cron hook. AccuracyBadge
(dashboard/scan/landing) is honest — "LEARNING" below MIN_SAMPLE, never a fake
number. Settled HIT/MISS chips overlay the live slate.

Real-time layer (Phase 1): Slate silent 60s auto-refresh (no flash, no wipe on
transient blips) + "SIGNAL LIVE · UPDATED Xs ago" freshness strip; Ticker LIVE
badge that flashes on fresh events.

Landing (Phase 3): TopSignals shows tonight's real top-3 A-rated grades + live
accuracy — the product shown, not described.

Founder pricing: FOUNDER_CODE_EXPIRY default 2026-06-30 → 2026-12-31 (had
lapsed, disabling every founder code + the ClaimMeter pitch). That expiry — not
a tier change — was the real cause of the 4 stripe test failures.

Backend 2255 (4 failing) → 2274 (all green; +19 new, +4 fixed). Web build exit 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/app.js

@@ -155,6 +155,10 @@ const snapshotReadRoutes = require('./routes/snapshot');
 app.use('/api/snapshot', snapshotReadRoutes);
 // Session 51 — Team Hub (roster + archetypes + graded props). Public, cached.
 app.use('/api/team', require('./routes/team'));
+// Session 55 — self-learning loop: the system's rolling accuracy record
+// (settled snapshot grades vs real results). Public, cache-only.
+app.use('/api/accuracy', require('./routes/accuracy'));
+app.use('/api/ledger', require('./routes/ledger'));
 const gameLinesRoutes = require('./routes/gameLines');
 app.use('/api/gamelines', gameLinesRoutes);
 const streaksRoutes = require('./routes/streaks');

src/routes/accuracy.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * GET /api/accuracy (Session 55) — the system's track record.
+ *
+ * Public, cache-only read of the rolling accuracy record written by
+ * outcomeService (settled snapshot grades vs real results). Powers the
+ * dashboard "A-rated: 68% hit rate" pill and the grade-card accuracy line.
+ * NEVER triggers settlement (that's the internal cron) → no API credits spent.
+ */
+
+const express = require('express');
+const { createRateLimit } = require('../middleware/rateLimit');
+const outcomeService = require('../services/outcomeService');
+
+const router = express.Router();
+router.use(createRateLimit({ windowMs: 60_000, max: 60 }));
+
+router.get('/', async (req, res) => {
+  try {
+    const acc = await outcomeService.getAccuracy();
+    res.set('Cache-Control', 'public, max-age=300');
+    return res.json(acc);
+  } catch (err) {
+    console.error('[accuracy]', err.message);
+    return res.status(200).json({ overall: null, sports: {}, min_sample: outcomeService.MIN_SAMPLE, updated_at: null });
+  }
+});
+
+module.exports = router;

src/routes/internal.js

@@ -159,4 +159,35 @@ router.post('/snapshot/:sport', async (req, res) => {
   }
 });
 
+/**
+ * POST /api/internal/outcomes/all (Session 55) — settle every sport's latest
+ * snapshot against real results + recompute the overall accuracy record. This
+ * is the self-learning loop's write path (the public /api/accuracy is read-only).
+ * Registered BEFORE /outcomes/:sport so "all" isn't captured as a sport.
+ */
+router.post('/outcomes/all', async (req, res) => {
+  const outcomes = require('../services/outcomeService');
+  try {
+    const results = await outcomes.settleAllOutcomes();
+    return res.json({ ok: true, results });
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error('[internal/outcomes/all] failed:', message);
+    return res.status(500).json({ ok: false, error: message });
+  }
+});
+
+router.post('/outcomes/:sport', async (req, res) => {
+  const outcomes = require('../services/outcomeService');
+  try {
+    const summary = await outcomes.settleSnapshot(req.params.sport);
+    await outcomes.recomputeOverall();
+    return res.json({ ok: true, summary: { sport: summary.sport, settled: summary.settled, pending: summary.pending, accuracy: summary.accuracy } });
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error('[internal/outcomes] failed:', message);
+    return res.status(500).json({ ok: false, error: message });
+  }
+});
+
 module.exports = router;

src/routes/ledger.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * GET /api/ledger/accuracy (Session 55) — grade-tier buckets for the ledger UI.
+ *
+ * The Next proxy `web/src/app/api/ledger/accuracy` has expected a `{ buckets }`
+ * shape since before a writer existed; the self-learning loop now fills it.
+ * Public, cache-only (reads outcomeService's persisted accuracy record).
+ */
+
+const express = require('express');
+const { createRateLimit } = require('../middleware/rateLimit');
+const outcomeService = require('../services/outcomeService');
+
+const router = express.Router();
+router.use(createRateLimit({ windowMs: 60_000, max: 60 }));
+
+router.get('/accuracy', async (req, res) => {
+  try {
+    const acc = await outcomeService.getAccuracy();
+    const buckets = outcomeService.accuracyBuckets(acc.overall);
+    res.set('Cache-Control', 'public, max-age=300');
+    return res.json({ buckets, overall: acc.overall && acc.overall.overall, updated_at: acc.updated_at });
+  } catch (err) {
+    console.error('[ledger/accuracy]', err.message);
+    return res.status(200).json({ buckets: [] });
+  }
+});
+
+module.exports = router;

src/routes/snapshot.js

@@ -12,23 +12,47 @@
 const express = require('express');
 const { createRateLimit } = require('../middleware/rateLimit');
 const { cacheGet } = require('../utils/redis');
+const { nameKey } = require('../utils/playerName');
 
 const router = express.Router();
 router.use(createRateLimit({ windowMs: 60_000, max: 60 }));
 
+// Session 55 — overlay settled outcomes (self-learning loop) onto the grades so
+// a completed prop can render "✅ HIT (2)" / "❌ MISS". Keyed by player+stat+line+side.
+function outcomeIndex(log) {
+  const map = {};
+  for (const o of Array.isArray(log) ? log : []) {
+    const side = String(o.side || 'O').toUpperCase() === 'U' ? 'U' : 'O';
+    map[`${nameKey(o.player)}|${String(o.stat).toLowerCase()}|${o.line}|${side}`] = o;
+  }
+  return map;
+}
+function attachOutcomes(grades, index) {
+  if (!index || Object.keys(index).length === 0) return grades;
+  return grades.map((g) => {
+    const side = String(g.direction || 'over').toLowerCase() === 'under' ? 'U' : 'O';
+    const o = index[`${nameKey(g.player || g.player_name)}|${String(g.stat_type || g.stat || '').toLowerCase()}|${g.line}|${side}`];
+    return o ? { ...g, outcome: { result: o.result, actual: o.actual } } : g;
+  });
+}
+
 router.get('/:sport', async (req, res) => {
   const sport = String(req.params.sport || '').toLowerCase();
   try {
-    const snap = await cacheGet(`snapshot:${sport}:latest`);
+    const [snap, outcomeLog] = await Promise.all([
+      cacheGet(`snapshot:${sport}:latest`),
+      cacheGet(`outcomes:${sport}:log`),
+    ]);
+    const idx = outcomeIndex(outcomeLog);
     if (snap && Array.isArray(snap.grades)) {
       res.set('Cache-Control', 'public, max-age=30');
-      return res.json({ sport, updated_at: snap.updated_at, grades: snap.grades, deltas: snap.deltas || [] });
+      return res.json({ sport, updated_at: snap.updated_at, grades: attachOutcomes(snap.grades, idx), deltas: snap.deltas || [] });
     }
     // Fallback: the grades envelope (no deltas yet).
     const env = await cacheGet(`grades:${sport}`);
     const grades = env && Array.isArray(env.grades) ? env.grades : [];
     res.set('Cache-Control', 'public, max-age=30');
-    return res.json({ sport, updated_at: env && env.updated_at, grades, deltas: [] });
+    return res.json({ sport, updated_at: env && env.updated_at, grades: attachOutcomes(grades, idx), deltas: [] });
   } catch (err) {
     console.error('[snapshot]', err.message);
     return res.status(200).json({ sport, grades: [], deltas: [] });

src/services/outcomeService.js

@@ -0,0 +1,296 @@
+'use strict';
+
+/**
+ * outcomeService — the self-learning loop (Session 55).
+ *
+ * VYNDR grades props but never checked whether it was right. This closes the
+ * loop: after games complete, settle each locked snapshot grade against the
+ * REAL result (did the player clear the line?), record hit/miss/push, and
+ * aggregate a rolling accuracy record by grade tier. That powers the accuracy
+ * display ("A-rated props: 68% hit rate"), the #1 trust builder — a system that
+ * shows its misses, not just its hits.
+ *
+ * Data source: the FREE MLB Stats API game log (mlbStatsAdapter.getPlayerStats)
+ * — the same source the grade pipeline already uses. Presence of a game-log row
+ * for the graded date ⇒ the game is FINAL. NBA/WNBA degrade to `pending` when
+ * their (usually offline) Python stats service returns nothing — never throw.
+ * Zero new dependency, zero paid API credits.
+ *
+ * Redis keys written:
+ *   outcomes:{sport}:log  — settled outcomes, newest first, cap 1000, deduped
+ *   accuracy:{sport}      — { overall, byGrade } over a trailing 30-day window
+ *   accuracy:overall      — same, aggregated across sports (dashboard header)
+ *
+ * Everything is injectable → the whole cycle is unit-tested with zero network.
+ */
+
+const { nameKey } = require('../utils/playerName');
+
+const LOG_CAP = 1000;
+const LOG_TTL = 30 * 24 * 3600;       // 30d — matches the accuracy window
+const ACC_TTL = 7 * 24 * 3600;
+const WINDOW_DAYS = 30;
+const MIN_SAMPLE = 8;                  // below this, callers should hide the pct
+const SPORTS = ['mlb', 'nba', 'wnba', 'soccer'];
+
+// VYNDR stat_type → the per-game field in a statsapi.mlb.com game-log row.
+// Mirrors featureCache.MLB_LOG_FIELD (settlement is a distinct concern, kept
+// self-contained so this service doesn't depend on test-only internals).
+const MLB_LOG_FIELD = {
+  total_bases: 'totalBases', home_runs: 'homeRuns', hits: 'hits', rbi: 'rbi',
+  runs: 'runs', stolen_bases: 'stolenBases', walks: 'baseOnBalls',
+  strikeouts: 'strikeOuts', earned_runs: 'earnedRuns', hits_allowed: 'hits',
+  innings_pitched: 'inningsPitched',
+};
+
+function statValue(statObj, statType) {
+  const f = MLB_LOG_FIELD[String(statType || '').toLowerCase()];
+  if (!f || !statObj) return null;
+  const n = parseFloat(statObj[f]);
+  return Number.isFinite(n) ? n : null;
+}
+
+// The UTC date AND the America/New_York date of an ISO timestamp — covers a
+// late game whose ET calendar date differs from UTC, without heavy TZ math.
+function dateStrings(ts) {
+  if (!ts) return [];
+  const d = new Date(ts);
+  if (isNaN(d.getTime())) return [];
+  const utc = d.toISOString().slice(0, 10);
+  let et = utc;
+  try {
+    et = new Intl.DateTimeFormat('en-CA', { timeZone: 'America/New_York' }).format(d);
+  } catch { /* Intl missing → UTC only */ }
+  return [...new Set([utc, et])];
+}
+
+const sideOver = (side) => {
+  const s = String(side || 'over').toLowerCase();
+  return s === 'over' || s === 'o';
+};
+
+// hit / miss / push for a graded side given the actual result and the line.
+function settleResult(side, actual, line) {
+  if (actual == null || line == null) return null;
+  const a = Number(actual), l = Number(line);
+  if (!Number.isFinite(a) || !Number.isFinite(l)) return null;
+  if (a === l) return 'push';
+  return sideOver(side) ? (a > l ? 'hit' : 'miss') : (a < l ? 'hit' : 'miss');
+}
+
+// Bucket a letter grade into a tier: A+ stands alone; A-/A → A; B±/B → B; …
+function gradeBucket(grade) {
+  const g = String(grade || '').trim().toUpperCase();
+  if (!g) return null;
+  if (g === 'A+') return 'A+';
+  return g[0];
+}
+
+const TIERS = ['A+', 'A', 'B', 'C', 'D', 'F'];
+
+function outcomeKey(o) {
+  return `${nameKey(o.player)}|${String(o.stat).toLowerCase()}|${o.line}|${sideOver(o.side) ? 'O' : 'U'}|${o.date}`;
+}
+
+/**
+ * Settle one sport's latest snapshot against real results. Returns
+ * { sport, settled, pending, log } and persists the merged log + accuracy.
+ * Never throws; a player/stat that can't be resolved is simply left pending.
+ *
+ * opts (all injectable): cacheGet, cacheSet, getPlayerStats(name, sport),
+ * now (ISO string).
+ */
+async function settleSnapshot(sport, opts = {}) {
+  const sp = String(sport || '').toLowerCase();
+  const deps = {
+    cacheGet: opts.cacheGet || require('../utils/redis').cacheGet,
+    cacheSet: opts.cacheSet || require('../utils/redis').cacheSet,
+    getPlayerStats: opts.getPlayerStats || defaultGetPlayerStats,
+    now: opts.now || (() => new Date().toISOString()),
+  };
+  const nowIso = deps.now();
+
+  const snap = await deps.cacheGet(`snapshot:${sp}:latest`);
+  const grades = snap && Array.isArray(snap.grades) ? snap.grades : [];
+  if (grades.length === 0) return { sport: sp, settled: 0, pending: 0, log: [] };
+
+  // Existing settled log (idempotency source).
+  const prevLog = normalizeLog(await deps.cacheGet(`outcomes:${sp}:log`));
+  const seen = new Set(prevLog.map(outcomeKey));
+
+  // Resolve each unique player's game log ONCE per run.
+  const players = [...new Set(grades.map((g) => g.player || g.player_name).filter(Boolean))];
+  const logByPlayer = {};
+  for (const player of players) {
+    try {
+      const stats = await deps.getPlayerStats(player, sp);
+      logByPlayer[player] = stats && stats.found && Array.isArray(stats.last10) ? stats.last10 : [];
+    } catch { logByPlayer[player] = []; }
+  }
+
+  const fresh = [];
+  let pending = 0;
+  for (const g of grades) {
+    const player = g.player || g.player_name;
+    const stat = g.stat_type || g.stat;
+    const side = g.direction || 'over';
+    const line = g.line;
+    const gradedTs = (g.gradedAt && g.gradedAt.timestamp) || snap.updated_at || nowIso;
+    const dates = dateStrings(gradedTs);
+    const log = logByPlayer[player] || [];
+    // Find the game played on the graded date.
+    const row = log.find((r) => r && r.date && dates.includes(r.date));
+    if (!row) { pending += 1; continue; }
+    const actual = statValue(row.stat, stat);
+    if (actual == null) { pending += 1; continue; }
+    const result = settleResult(side, actual, line);
+    if (!result) { pending += 1; continue; }
+    const outcome = {
+      player, stat, line, side: sideOver(side) ? 'O' : 'U',
+      grade: g.grade, actual, result, date: row.date,
+      gradedAt: gradedTs, settledAt: nowIso,
+    };
+    const key = outcomeKey(outcome);
+    if (seen.has(key)) continue;           // idempotent — already settled
+    seen.add(key);
+    fresh.push({ ...outcome, key });
+  }
+
+  // Merge (newest first), cap.
+  const merged = [...fresh, ...prevLog].slice(0, LOG_CAP);
+  await deps.cacheSet(`outcomes:${sp}:log`, merged, LOG_TTL);
+
+  const accuracy = computeAccuracy(sp, merged, nowIso);
+  await deps.cacheSet(`accuracy:${sp}`, accuracy, ACC_TTL);
+
+  return { sport: sp, settled: fresh.length, pending, log: merged, accuracy };
+}
+
+// Aggregate a settled log into an accuracy record over the trailing window.
+function computeAccuracy(sport, log, nowIso, windowDays = WINDOW_DAYS) {
+  const cutoff = new Date(nowIso).getTime() - windowDays * 24 * 3600 * 1000;
+  const inWindow = (log || []).filter((o) => {
+    const t = new Date(`${o.date}T12:00:00Z`).getTime();
+    return Number.isFinite(t) && t >= cutoff;
+  });
+  const bucketFor = (grade) => {
+    const b = gradeBucket(grade);
+    return TIERS.includes(b) ? b : null;
+  };
+  const blank = () => ({ hits: 0, misses: 0, pushes: 0, total: 0, pct: null });
+  const byGrade = {};
+  for (const t of TIERS) byGrade[t] = blank();
+  const overall = blank();
+  for (const o of inWindow) {
+    const tier = bucketFor(o.grade);
+    const targets = [overall];
+    if (tier) targets.push(byGrade[tier]);
+    for (const bucket of targets) {
+      if (o.result === 'hit') bucket.hits += 1;
+      else if (o.result === 'miss') bucket.misses += 1;
+      else if (o.result === 'push') bucket.pushes += 1;
+    }
+  }
+  const finalize = (b) => {
+    b.total = b.hits + b.misses + b.pushes;
+    const decided = b.hits + b.misses;
+    b.pct = decided > 0 ? Math.round((b.hits / decided) * 100) : null;
+    return b;
+  };
+  finalize(overall);
+  for (const t of TIERS) finalize(byGrade[t]);
+  return {
+    sport, updated_at: nowIso, window_days: windowDays,
+    sample: overall.total, min_sample: MIN_SAMPLE,
+    overall, byGrade,
+  };
+}
+
+function normalizeLog(raw) {
+  if (Array.isArray(raw)) return raw;
+  if (raw && Array.isArray(raw.log)) return raw.log;
+  return [];
+}
+
+async function defaultGetPlayerStats(name, sport) {
+  if (String(sport).toLowerCase() === 'mlb') {
+    return require('./adapters/mlbStatsAdapter').getPlayerStats(name);
+  }
+  // NBA/WNBA/soccer: no free settled-result feed here → pending.
+  return { found: false };
+}
+
+/**
+ * Recompute the cross-sport accuracy:overall record from every sport's log.
+ * Called after settling. Deps: cacheGet, cacheSet, now.
+ */
+async function recomputeOverall(opts = {}) {
+  const deps = {
+    cacheGet: opts.cacheGet || require('../utils/redis').cacheGet,
+    cacheSet: opts.cacheSet || require('../utils/redis').cacheSet,
+    now: opts.now || (() => new Date().toISOString()),
+  };
+  const nowIso = deps.now();
+  const logs = [];
+  for (const sp of SPORTS) {
+    const l = normalizeLog(await deps.cacheGet(`outcomes:${sp}:log`));
+    logs.push(...l);
+  }
+  const acc = computeAccuracy('overall', logs, nowIso);
+  await deps.cacheSet('accuracy:overall', acc, ACC_TTL);
+  return acc;
+}
+
+/** Settle every sport, then recompute the overall record. Cron entrypoint. */
+async function settleAllOutcomes(opts = {}) {
+  const results = [];
+  for (const sp of SPORTS) {
+    try { results.push(await settleSnapshot(sp, opts)); }
+    catch (e) { results.push({ sport: sp, settled: 0, pending: 0, error: e.message }); }
+  }
+  await recomputeOverall(opts);
+  return results;
+}
+
+/**
+ * Read the persisted accuracy record for the public endpoint. Cold-cache safe:
+ * returns an empty-but-valid shape. Deps: cacheGet.
+ */
+async function getAccuracy(opts = {}) {
+  const cacheGet = opts.cacheGet || require('../utils/redis').cacheGet;
+  const overall = await cacheGet('accuracy:overall');
+  const sports = {};
+  for (const sp of SPORTS) {
+    const a = await cacheGet(`accuracy:${sp}`);
+    if (a) sports[sp] = a;
+  }
+  return {
+    overall: overall || computeAccuracy('overall', [], new Date().toISOString()),
+    sports,
+    min_sample: MIN_SAMPLE,
+    updated_at: overall && overall.updated_at ? overall.updated_at : null,
+  };
+}
+
+/** Flatten an accuracy record into the ledger `buckets` shape. */
+function accuracyBuckets(acc) {
+  if (!acc || !acc.byGrade) return [];
+  return TIERS
+    .map((tier) => {
+      const b = acc.byGrade[tier] || {};
+      return { grade: tier, hits: b.hits || 0, total: b.total || 0, pct: b.pct };
+    })
+    .filter((b) => b.total > 0);
+}
+
+module.exports = {
+  settleSnapshot,
+  settleAllOutcomes,
+  recomputeOverall,
+  getAccuracy,
+  computeAccuracy,
+  accuracyBuckets,
+  SPORTS,
+  MIN_SAMPLE,
+  __internals: { settleResult, gradeBucket, dateStrings, statValue, outcomeKey, MLB_LOG_FIELD, TIERS },
+};

src/services/stripeService.js

@@ -31,7 +31,11 @@ const PRICE_UNCONFIGURED = '__unconfigured__';
 // VYNDR is the canonical brand promo. BETONBLK stays in the default list so
 // codes distributed before the rebrand keep redeeming during the transition.
 const VALID_FOUNDER_CODES = (process.env.FOUNDER_CODES || 'FOUNDER2026,VYNDR,BETONBLK,EARLYBIRD').split(',');
-const FOUNDER_EXPIRY = new Date(process.env.FOUNDER_CODE_EXPIRY || '2026-06-30');
+// Session 55 — founder pricing is still an active launch lever (the ClaimMeter
+// scarcity meter + the $14.99/$34.99 founder tiers advertise it), so the default
+// window runs through 2026. The 2026-06-30 default had silently lapsed (current
+// date 2026-07-10), disabling every founder code. Operators override via env.
+const FOUNDER_EXPIRY = new Date(process.env.FOUNDER_CODE_EXPIRY || '2026-12-31');
 
 function isFounderCodeValid(code) {
   if (!code) return false;

src/snapshotScheduler.js

@@ -27,6 +27,10 @@ function startSnapshotScheduler(opts = {}) {
     return null;
   }
   const runAll = opts.runAllSnapshots || require('./services/snapshotService').runAllSnapshots;
+  // Session 55 — self-learning loop. Settle the PRIOR snapshot's grades against
+  // real (now-completed) results BEFORE grading the fresh slate, so the accuracy
+  // record reflects yesterday's games each cycle.
+  const settleAll = opts.settleAllOutcomes || require('./services/outcomeService').settleAllOutcomes;
   const now = opts.now || (() => new Date());
   let lastFiredSlot = null;
 
@@ -38,6 +42,13 @@ function startSnapshotScheduler(opts = {}) {
     const slot = `${d.getUTCFullYear()}-${d.getUTCMonth()}-${d.getUTCDate()}-${h}`;
     if (slot === lastFiredSlot) return; // fire once per slot
     lastFiredSlot = slot;
+    try {
+      const settled = await settleAll();
+      const totalSettled = settled.reduce((n, r) => n + (r.settled || 0), 0);
+      console.log(`[outcomes] cron fired ${h}:00 UTC — ${totalSettled} props settled vs real results`);
+    } catch (e) {
+      console.warn('[outcomes] settle run failed:', e.message);
+    }
     try {
       const results = await runAll();
       const ok = results.filter((r) => r.status === 'ok');