Session 58: Phase 1 — Truth Infrastructure (2327 tests)

ledger_entries is live (migration 019 applied to prod, RLS + NULLS NOT
DISTINCT dedupe verified against the real database). Every grade now
persists, settles against the real result, and carries closing-line value.

- ledgerService: pipeline pre-grade upserts (public model record, user_id
  null, idempotent), closing capture on every snapshot (last write before
  game start = the close), settlement with SIGNED CLV (over = locked -
  closing; beat/faded/flat), 30d model aggregate with the hard n>=20 rule.
- Write paths: snapshotService -> ledger (priority path); Next /api/scan ->
  ledger for authenticated users only (anon never touches the public
  record). Refused reads write nothing and don't burn a scan.
- Honest refusal (work-order 1.5): no projection => insufficient_data,
  grade null, "INSUFFICIENT DATA - no read" UI. The web gradeAdapter no
  longer displays the line as the model projection (the audit's
  model==line / +0% edge degenerate); the card renders absent states.
  projectionFor is sport-aware (l5 -> l20 -> {stat}_per_90 -> xG).
- /ledger: MY READS | MODEL tabs; model header shows hit% + beat-close%
  only at n>=20, else RECORD BUILDING + live pending count. ModelRecord
  deferred-render strip on landing + player hero. CLV + outcome chips,
  revised_from_grade strikethrough (Phase 2.5 ready).
- SYNC (Task 5): thresholds vs SNAPSHOT_EXPECTED_INTERVAL (normal <1.5x,
  amber >=1.5x, STALE red >=3x) via /api/snapshot/summary.
- Phase 2.5 logged in specs/vyndr-roadmap.md (build after Phase 3).
- Data-semantics hardening: strict null-safe numeric parsing everywhere a
  market value is handled (Number(null)===0 would have fabricated lines).

Backend 2309 -> 2327 tests (201 suites), web build exit 0.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/routes/internal.js

@@ -180,6 +180,23 @@ router.post('/outcomes/all', async (req, res) => {
   }
 });
 
+/**
+ * POST /api/internal/ledger/settle (Session 58, Phase 1) — settle the
+ * persistent ledger (outcome + actual_value + CLV) across every sport.
+ * Idempotent — safe to re-run; already-settled rows are never touched.
+ */
+router.post('/ledger/settle', async (req, res) => {
+  const ledger = require('../services/ledgerService');
+  try {
+    const results = await ledger.settleAllLedgers();
+    return res.json({ ok: true, results });
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    console.error('[internal/ledger/settle] failed:', message);
+    return res.status(500).json({ ok: false, error: message });
+  }
+});
+
 router.post('/outcomes/:sport', async (req, res) => {
   const outcomes = require('../services/outcomeService');
   try {

src/routes/ledger.js

@@ -1,20 +1,45 @@
 'use strict';
 
 /**
- * GET /api/ledger/accuracy (Session 55) — grade-tier buckets for the ledger UI.
+ * /api/ledger — the truth surface (Sessions 55 + 58).
  *
- * 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).
+ *   GET /accuracy — grade-tier buckets (Session 55, snapshot-log based).
+ *   GET /mine     — the caller's own ledger_entries, newest first (Phase 1).
+ *   GET /model    — the PUBLIC model record (user_id NULL rows) + the 30d
+ *                   aggregate {hit_pct, beat_close_pct, pending}. Percentages
+ *                   are null below MIN_AGG_SAMPLE (20) — the UI renders
+ *                   "RECORD BUILDING" instead. Never a % on a small n.
  */
 
 const express = require('express');
 const { createRateLimit } = require('../middleware/rateLimit');
+const { requireAuth } = require('../middleware/auth');
 const outcomeService = require('../services/outcomeService');
+const ledgerService = require('../services/ledgerService');
+const { nameKey } = require('../utils/playerName');
 
 const router = express.Router();
 router.use(createRateLimit({ windowMs: 60_000, max: 60 }));
 
+const VALID_SPORTS = new Set(['nba', 'mlb', 'wnba', 'soccer']);
+const VALID_TIERS = new Set(['A', 'B', 'C', 'D', 'F']);
+const ROW_COLUMNS = 'id, player_key, player_name, sport, stat, line, side, locked_odds, book, grade, edge, confidence, model_value, graded_at, game_id, game_date, closing_line, closing_odds, clv, clv_result, outcome, actual_value, settled_at, revised_from_grade';
+
+function sbOrNull() {
+  try {
+    if (!ledgerService.__internals.isConfigured()) return null;
+    return require('../utils/supabase').getSupabaseServiceClient();
+  } catch { return null; }
+}
+
+function applyFilters(query, req) {
+  const sport = String(req.query.sport || '').toLowerCase();
+  const tier = String(req.query.tier || req.query.grade || '').toUpperCase();
+  if (VALID_SPORTS.has(sport)) query = query.eq('sport', sport);
+  if (VALID_TIERS.has(tier)) query = query.ilike('grade', `${tier}%`);
+  return query;
+}
+
 router.get('/accuracy', async (req, res) => {
   try {
     const acc = await outcomeService.getAccuracy();
@@ -27,4 +52,58 @@ router.get('/accuracy', async (req, res) => {
   }
 });
 
+// The caller's own reads. Service-role read scoped to req.user.id — clients
+// never query the table directly (RLS blocks writes; reads go through here).
+router.get('/mine', requireAuth, async (req, res) => {
+  const sb = sbOrNull();
+  if (!sb) return res.json({ entries: [] });
+  try {
+    const limit = Math.min(200, Math.max(1, Number(req.query.limit) || 100));
+    let q = sb.from('ledger_entries')
+      .select(ROW_COLUMNS)
+      .eq('user_id', req.user.id);
+    q = applyFilters(q, req);
+    const { data, error } = await q
+      .order('graded_at', { ascending: false })
+      .limit(limit);
+    if (error) throw new Error(error.message);
+    return res.json({ entries: data || [] });
+  } catch (err) {
+    console.error('[ledger/mine]', err.message);
+    return res.status(200).json({ entries: [] });
+  }
+});
+
+// The public model record: every pipeline pre-grade, settled or pending,
+// misses included. This is the product's proof surface.
+router.get('/model', async (req, res) => {
+  const sb = sbOrNull();
+  try {
+    const aggregate = await ledgerService.getModelAggregate({
+      sport: VALID_SPORTS.has(String(req.query.sport || '').toLowerCase())
+        ? String(req.query.sport).toLowerCase() : undefined,
+      // VYNDR-on-player (work-order 1.4/5.2): per-player public record.
+      playerKey: req.query.player ? nameKey(String(req.query.player).slice(0, 60)) : undefined,
+    });
+    let entries = [];
+    if (sb) {
+      const limit = Math.min(200, Math.max(1, Number(req.query.limit) || 60));
+      let q = sb.from('ledger_entries')
+        .select(ROW_COLUMNS)
+        .is('user_id', null);
+      q = applyFilters(q, req);
+      const { data, error } = await q
+        .order('graded_at', { ascending: false })
+        .limit(limit);
+      if (error) throw new Error(error.message);
+      entries = data || [];
+    }
+    res.set('Cache-Control', 'public, max-age=60');
+    return res.json({ entries, aggregate, min_sample: ledgerService.MIN_AGG_SAMPLE });
+  } catch (err) {
+    console.error('[ledger/model]', err.message);
+    return res.status(200).json({ entries: [], aggregate: null, min_sample: ledgerService.MIN_AGG_SAMPLE });
+  }
+});
+
 module.exports = router;

src/routes/snapshot.js

@@ -61,8 +61,15 @@ router.get('/summary', async (req, res) => {
     const updated_at = reads.map((r) => r.updated_at).filter(Boolean).sort().pop() || null;
     const sports = {};
     for (const r of reads) sports[r.sport] = r.graded;
+    // Session 58 (Task 5) — the SYNC badge thresholds key off the pipeline's
+    // EXPECTED cadence, not a flat 5 minutes: normal < 1.5x, amber ≥ 1.5x,
+    // STALE red ≥ 3x. Default = the 5h max cron gap; when Phase 2.5's
+    // intraday refresh ships, drop the env value and the badge goes live
+    // with zero UI changes.
+    const expected_interval_s = Number(process.env.SNAPSHOT_EXPECTED_INTERVAL) > 0
+      ? Number(process.env.SNAPSHOT_EXPECTED_INTERVAL) : 18000;
     res.set('Cache-Control', 'public, max-age=30');
-    return res.json({ graded, updated_at, sports });
+    return res.json({ graded, updated_at, sports, expected_interval_s });
   } catch (err) {
     console.error('[snapshot/summary]', err.message);
     return res.status(200).json({ graded: 0, updated_at: null, sports: {} });