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>

CLAUDE.md

@@ -710,6 +710,43 @@ phased plan in the Session-57 conversation / BUILD-STATE Next section).
 - **Empty slates use `web/src/lib/emptyState.js`** (month-aware per-sport
   copy). It's CommonJS + unit-tested; add sports there, not inline.
 
+## Phase 1 — Truth Infrastructure (Session 58 — non-obvious)
+- **DATA SEMANTICS RULE (system-wide):** VYNDR never generates lines/odds —
+  market values are REAL book numbers captured at a timestamp; only
+  `model_value`/grade/edge/confidence are model output, always labeled MODEL
+  in the UI. Any path that would fill in a market value must show an absent
+  state. `Number(null) === 0` is the classic fabrication bug — use
+  `numOrNull` (ledgerService) style strict parsing.
+- **`ledger_entries`** (migration 019, APPLIED): user_id NULL rows = the
+  PUBLIC model record (pipeline-only — never write anon scans there!).
+  Dedupe = `UNIQUE NULLS NOT DISTINCT (user_id, player_key, stat, line,
+  side, game_id)`; upserts use `ignoreDuplicates: true` so re-runs never
+  overwrite the original lock. RLS: clients read own rows + public rows;
+  ALL writes via service role. player_key = `nameKey()`.
+- **Write paths:** pipeline → `snapshotService` calls
+  `ledgerService.recordPipelineGrades` + `captureClosing` (best-effort,
+  never breaks the snapshot; no-op without SUPABASE env). User scans →
+  the NEXT `/api/scan` route (`writeLedgerEntry`), authed users only.
+- **Closing/CLV:** captureClosing overwrites today's unsettled rows'
+  closing_line/odds on EVERY snapshot — last write before game start is the
+  close. CLV is SIGNED BY SIDE: over = locked − closing (positive = market
+  moved toward the grade = 'beat'); under = inverse. Settlement
+  (`settleLedger`) runs in the scheduler's pre-grade settle pass and via
+  POST /api/internal/ledger/settle; idempotent (`.is('outcome', null)` guard).
+- **Insufficient data (work-order 1.5):** `analyzeViaEngine1` REFUSES
+  (grade null + `insufficient_data: true`) when `projectionFor` finds no
+  model reference (l5→l20→`{stat}_per_90`→xG-for-goals). gradeSlateService
+  filters refusals out of the slate; parlay legs degrade to the F-stub; the
+  scan route writes nothing and doesn't burn a scan. If you add a sport,
+  make sure its feature extractor emits a projection field or every prop
+  refuses.
+- **n≥20 rule:** `getModelAggregate` returns `hit_pct`/`beat_close_pct` as
+  NULL under 20 settles; every surface (ledger MODEL tab, `ModelRecord`)
+  renders "RECORD BUILDING" instead. Never render a % on a small sample.
+- **SYNC thresholds** come from `SNAPSHOT_EXPECTED_INTERVAL` (s; default
+  18000) via /api/snapshot/summary `expected_interval_s`. Phase 2.5 drops
+  the value to the intraday cadence — no UI change needed.
+
 ## Active Skills
 - vyndr-voice (all user-facing output)
 - prop-analysis (grading methodology)