vyndr/BACKEND_HANDOFF.md

# VYNDR — Backend / Frontend Data Contract (BACKEND_HANDOFF.md)

**Canonical frontend↔backend data contract for the Player Intelligence System.**
Every future session references this. Authored Session 44 from the shipped
implementation (Sessions 42–44). When an endpoint or component shape changes,
update this file in the same commit.

> Naming: archetypes are **VYNDR Originals** (TORCH, BOMBER, ALPHA, …). The old
> descriptive labels live on each archetype as `legacyName` and are NEVER shown.

---

## 1. Archetypes (`src/services/archetypeService.js`)

`classify(sport, stats) → { sport, primary, secondary|null, blend }`

```
primary | secondary : {
  name, legacyName, tag, sport, color (#hex), glyph (key),
  description, propDNA: { reliable: string[], volatile: string[] }, education
}
blend : [{ archetype: <NAME>, weight: 0..1 }]   // normalized, top 4, sums ~1
```

**Roster (41):** see `ARCHETYPES` registry. Colors are unique *within* a sport,
reused *across* sports. Frontend visual map (color/glyph/desc) is mirrored in
`web/src/lib/archetypes.js` — keep colors identical (a test enforces it).

- **NBA (15):** TORCH, CONDUCTOR, FORTRESS, ARTILLERY, SURGE, DUAL THREAT,
  CONNECTOR, FASTBREAK, PAINT BOSS, LOCKDOWN, SWITCHBOARD, ARCHITECT, PISTON,
  SENTINEL, IGNITER
- **WNBA-unique (5):** DISTRIBUTOR, SHIELD, RANGE, SPARK, ANCHOR (plus reused NBA)
- **MLB (15):** BOMBER, BRUSH, DRIVER, ALPHA, WHIFF, GHOST, HYBRID, FLEX,
  WORKHORSE, CATALYST, MIRROR, HAMMER, SINKER, BRIDGE, SWITCH
- **Soccer (6):** FINISHER, MAESTRO, TOWER, MOTOR, BLADE, WALL

Classifier input shapes:
- NBA/WNBA: `{ ppg, rpg, apg, bpg, spg, threes, usg, fg3a, pos, bench }`
- MLB hitter: `{ avg, hr, rbi, sb, ops, runs, k_rate, doubles }`
- MLB pitcher: `{ era, k9, whip, ip_per_start, saves, role: 'SP'|'RP'|'CL' }`

---

## 2. Stats API (`src/routes/stats.js`, mounted at `/api/stats`)

All player-intelligence endpoints are public, rate-limited 60/min, and ALWAYS
return 200 with a valid (possibly empty) shape — the UI must never hard-fail.
Browser must hit the **Next proxy** under `web/src/app/api/stats/...`, never
Express directly.

### `GET /api/stats/player/:name?sport=nba`
```
{
  player, sport, team, found: boolean,
  archetype: { primary, secondary, blend },     // §1
  propDNA: { reliable, volatile },
  education: string,
  season:  [{ k, v, lg? }],                      // display rows (mono)
  last10:  [{ d, opp, res?, stat }],
  splits:  [{ k, a, b }],
  gradeHistory: [{ grade, prop, hit?, miss? }],
  activeProps:  [{ stat, line, side: 'O'|'U', grade, confidence }],
  intel: [{ label, kind: 'form'|'grade'|'plain', value, score?, color }],
  injury: { label, note, cascade } | null
}
```
`found` is true when real season stats OR tonight's graded props exist. MLB stats
come from `mlbStatsAdapter.getPlayerStats(name)`; NBA/WNBA from `nbaStatsClient`
(degrades to `found:false` when the Python service is offline).

### `GET /api/stats/leaders?sport=mlb&stat=hits&limit=10`
```
{ sport, stat|null, leaders: [{ player, team, stat, line, side, grade, confidence }] }
```
Source: the `grades:{sport}` cache (tonight's graded slate, by confidence desc).

### `GET /api/stats/game/:id?sport=nba`
ESPN game summary (injuries, leaders, ESPN Bet odds, box score) or `{error}`.

### `GET /api/stats/lineup/:team?sport=mlb`  (Session 43)
`{ sport, team, lineup: [{ player, position, battingOrder, projectedMinutes }] }`
MLB returns the probable starting pitcher from the schedule.

### `GET /api/stats/depth/:team?sport=nba`
`{ sport, team, positions: [{ position, starter, backup, thirdString }] }`

### `GET /api/stats/cascade/:player?sport=nba&team=SA`
`{ sport, player, cascade: [{ player, stat, delta: '+x%', reason }] }`
Usage redistribution weighted by archetype (SURGE benefits most).

---

## 3. Grade Result Card (`web/src/components/vyndr/GradeResultCard.tsx`)

`GradeResultData` (built by `web/src/lib/gradeAdapter.js` `mapScanToGradeResult`):
core fields (player, team, sport, stat, line, side, grade, confidence, edge,
projection, signals[], killConditions[], books[], altLadder[]) **plus** optional
Player-Intelligence fields that self-hide when absent:
```
archetypeBlend?: [{ archetype, weight }]
propDNA?:        { reliable: string[], volatile: string[] }
statContext?:    { season?, last10?, vsOpp? }
vyndrIntel?:     { form?, usage?, matchup?, rest? }
```
The engine (`analyzeViaEngine1`) attaches snake_case fields
(`season_avg`/`last10_avg`/`form`/`usage`/`matchup_grade`/`rest`, and when a
season line is available, `archetype`/`archetype_blend`/`prop_dna`); the adapter
maps them in. Archetype at grade time requires a multi-stat season line — until
the snapshot pipeline supplies it, the archetype strip stays hidden.

---

## 4. Game Card (`web/src/components/vyndr/GameCard.tsx`)

`GameCardData` core (id, sport, away/home, time, venue, lines[], …) **plus**:
```
playerStrips?: [{ player, team, archetype?: {primary, secondary?}, stats: [{label,value}], props: [{stat,line,side,grade}] }]
pitchers?:     { away: {name, era, archetype?}, home: {name, era, archetype?} }
```
Built by `slateAdapter.mapScheduleToGameCards` (`groupPropsByPlayer` +
`mapPitchers`). The card prefers `playerStrips` (name once, horizontal) over
legacy per-prop rows. Book chips use `web/src/lib/books.js` brand colors.

**Headshots (Wave 2A/2B):** each enriched grade + player strip may carry
`playerId` (MLBAM), `espnId` (ESPN athlete id), and `headshotUrl` (a RESOLVED
absolute ESPN href). `PlayerAvatar` prefers `headshotUrl` (exact URL, never
404s) → else constructs from `(sport, playerId|espnId)` → else a team-colored
monogram. `espnId`/`headshotUrl` come from `snapshotService`: primarily the
per-player stats resolve, and — when that misses (the flaky NBA/WNBA fallback)
— from `espnAthleteIndex.buildEspnAthleteIndex(sport)`, which harvests ESPN
schedule→summary/boxscore/leaders/injuries/roster feeds (free, cached, MLB→{}).
Soccer resolves ONLY via a direct `headshotUrl` (no constructed URL); absent →
honest monogram (a free `API_FOOTBALL_KEY` is the reliable soccer path, unwired).

---

## 5. Stat Strip (`web/src/components/vyndr/StatStrip.tsx`)

`compact` (game cards) | `expanded` (profile hero / grade result). HARD RULE: the
player name appears ONCE; stats flow horizontally in JetBrains Mono. Props render
inline with `GradeBadge`. `onPlayerClick` → `/player/:name?sport=` (`lib/playerHref.js`).

---

## 5a. Normalization is applied at the SNAPSHOT source (Session 48)

`snapshotService.runSnapshot` normalizes every grade's player name (de-dotted
display) and dedupes to ONE grade per `nameKey|stat_type` (highest confidence)
BEFORE writing `grades:{sport}` + `snapshot:{sport}:latest`. Every downstream
consumer (GameCard overlay, `/api/snapshot`, `/leaders`, profile `activeProps`)
therefore receives clean, merged names. New consumers don't need their own
normalization — but UI lists built from RAW odds (e.g. the scan player grid)
must group by `nameKey` + display `normalizeName().display`.

## 5b. Player name normalization (Session 46)

`src/utils/playerName.js` (+ identical `web/src/lib/playerName.js`) is the ONE
source of truth for comparing/deduping names. `normalizeName(raw)` →
`{ display, key }`: `display` strips periods + de-dots the suffix (keeps accents
+ casing); `key` is accent-folded, lowercased, suffix-stripped for comparison.
Used by snapshot grouping, `slateAdapter` (grade index + player strips), and
`playerIntelService` so "A.J. Ewing"/"AJ Ewing" and "Jazz Chisholm"/"Jazz
Chisholm Jr." collapse to one player.

## 5c. MLB intel features (Session 46)

`buildIntelFields` (grade-card STAT CONTEXT + VYNDR INTELLIGENCE) reads
`l5_avg`/`l10_avg`/`l20_avg`/`opp_rank_stat`/`rest_days` from the feature vector.
MLB game logs are now wired into `featureCache.gameLogFeatures` via
`mlbStatsAdapter.getPlayerStats` (the old Python game-log path was NBA/WNBA-only,
so MLB props had no intel). `buildIntelFields(features, { playerStats, projection })`
also accepts fallbacks so partial intel still renders.

## 5d. MLB probable pitchers (Session 46)

`GET /api/schedule/:sport/pitchers` (MLB only) → `{ sport, date, games:
[{ home:{team,pitcher,era}, away:{...} }] }` from `probablePitchers` /
`mlbStatsAdapter.getScheduleWithPitchers` (the ESPN schedule lacks them). The
Slate builds a team→pitcher map (`slateAdapter.buildPitcherMap` /
`pitchersForGameTeams`) and attaches `pitchers` to MLB GameCardData.

## 6. Freshness & caching

- Schedule cache TTL ≤ 30 min (`scheduleService`). Frontend filters completed
  games older than 24h out of the slate (`slateAdapter.isRelevantGame`).
- Player props: PropLine primary (3-key rotation), The-Odds-API backup.
- `grades:{sport}` cache (TTL 2h) is written by `gradeSlateService` on a fresh
  odds fetch; it feeds `/leaders` + the player card's `activeProps`.

---

## 7. Accuracy / self-learning loop (`outcomeService`, Session 55)

The system's track record — settled grades vs real results. Written by
`outcomeService.settleAllOutcomes()` (cron, before grading); read-only endpoints.

### `GET /api/accuracy`  (public, cached 5m)
```
{
  overall: {                       // aggregate across sports
    sport: 'overall', updated_at, window_days: 30, sample,
    overall: { hits, misses, pushes, total, pct|null },   // pct excludes pushes
    byGrade: { 'A+':{…}, 'A':{…}, 'B':{…}, 'C':{…}, 'D':{…}, 'F':{…} }
  } | null,
  sports: { mlb?: <record>, nba?: <record>, … },  // same shape per sport
  min_sample: 8,                   // below this, show "LEARNING" not a %
  updated_at: string | null
}
```

### `GET /api/ledger/accuracy`  (public) — the ledger `buckets` shape
```
{ buckets: [{ grade, hits, total, pct|null }], overall, updated_at }
```

### Settled outcome overlay
`GET /api/snapshot/:sport` grades may carry `outcome: { result:'hit'|'miss'|
'push', actual:number }` once the game is final. `AccuracyBadge` +
`StatStrip.OutcomeChip` render these. Frontend proxy: `web/src/app/api/accuracy`.

### S6 (A1 board) — display enrichments on the same payloads
- `GET /api/snapshot/:sport` grades may also carry:
  - `last10_dots: boolean[]` — last ≤10 games vs the LOCKED line, newest
    first (server-side from `rosterlogs:{sport}` via `services/last10Dots`).
    Absent when there's no real log / no accessor for the stat.
  - `history: [{ t: string, line: number }]` — REAL captured line points
    from the intraday refresh (seeded with the locked line, deduped when
    flat, capped 24). The StatStrip sparkline renders only at ≥3 points.
  `slateAdapter.buildPlayerStripsFromProps` threads both onto `StripProp`
  (`last10Dots` / `history`); `StatStrip.DotStrip` + `LineSparkline` render.
- `GET /api/ledger/model` `aggregate` may carry `clv_distribution:
  [{ label, min, max, side:'faded'|'flat'|'beat', count }]` — seven ordered
  buckets over settled signed CLV ([-2,-1) … (1,2], outliers clamped into
  the edge buckets). **null below the n≥20 gate** (the gate lives in
  `getModelAggregate`, nowhere else). Ledger MODEL header renders the strip.
- Global search: `window.__search()` opens the ⌘K SearchModal (players via
  `/api/players/search` per sport; teams from the static `web/src/lib/teams.js`).

## 8. Public ledger profiles (`src/routes/profiles.js`, A1 Session 10)

Strava-for-betting v1. Table `public_profiles` (migration 022 — apply
before deploy). PRIVATE BY DEFAULT; one explicit publish toggle in Settings.

### `GET /api/profiles/:handle`  (public, cached 60s)
Published only. Unknown AND unpublished return the SAME 404 body
(`{ error: 'Profile not found' }`) — no existence leak.
```
{
  handle: string,
  aggregate: <getModelAggregate shape, scoped to the user via userId>,
  entries: [<same columns as /api/ledger, SETTLED rows only, newest 50>],
  min_sample: 20                    // below this, RECORD BUILDING — never a %
}
```

### HOUSE profile (Wave 5A, D2)
The reserved handle `HOUSE_HANDLE` (env, default `vyndr`) resolves to the
PUBLIC model record (`getModelAggregate()` with NO userId → the `user_id=NULL`
ledger rows) WITHOUT a `public_profiles` row, and is ALWAYS public (the
partner-pitch weapon). Same response shape + two extra fields:
`{ ..., house: true, label: 'VYNDR MODEL · PUBLIC RECORD' }`. Entries are the
public settled rows (`user_id IS NULL`, misses included). Reserved before the
publish lookup — a user who claims it is shadowed. Every OTHER handle keeps the
private-by-default, byte-identical-404 contract. It never 404s (a fetch failure
degrades to an honest empty/building state). Portrait share crop: route handler
`GET /u/[handle]/portrait` → 1080×1350 PNG (real aggregate or tagline fallback).

### `GET|POST /api/profiles/me`  (requireAuth)
GET → `{ profile: { handle, published, created_at } | null }`.
POST `{ handle, published }` → upsert own row (service role). Handle must
match `^[a-z0-9_]{3,20}$` (400); a handle owned by another user → 409.
`published` flips ONLY on boolean `true`.

Frontend: `/u/[handle]` (OPEN route, server shell + client record + OG card,
Node runtime) via proxies `web/src/app/api/profiles/me|[handle]`.

## Value Engine fields (Model Train arc 1, 2026-07-19)
Every graded read (snapshot `grades:{sport}`, `/api/snapshot/:sport`, `/api/hero-prop`,
`/api/scan`) now carries — all OPTIONAL + self-hiding when absent:
- `ev_pct` (number) — expected value % at the graded side's ACTUAL price
  (model prob × decimal − 1). The ranking signal on boards + hero, replacing raw
  |model−consensus|.
- `value` (bool) — the read passes BOTH gates: takeable price AND ev_pct ≥
  VALUE_EV_THRESHOLD. Grade = read quality; `value` = "the price pays you." An A
  without `value` is honest (right read, price gone).
- `takeable` (bool) — the graded-side price is inside the promotable band
  (TAKEABLE_ODDS_CEILING −160 .. +200).
- **The value triplet** — `book_odds` · `fair_odds` · `model_odds` (all American):
  the book's price, the de-vigged FAIR price (two-way multiplicative de-vig;
  present only when BOTH sides were priced — else absent, never faked), and the
  model's implied price. This is the story to render: "book −145 · vig-free −132
  · model −110". Also `fair_prob`, `overround`, `devig_method`.
- Suppression reasons ride on refused reads: `suppressed` + `suppressed_reason`
  (`juiced_no_edge` / `rare_event_under`) + `reasoning.summary` (branded "No
  read" copy) — for the visible-refusal moment (Model Train step 10).

DESIGN: the triplet + VALUE marker + refusal copy are Session-2 design surfaces
(reveal card, board row, hero). Backend ships the fields; rendering is Design's.

## Book Comparison — `/api/books` (per-book price display, snapshot-locked)

Data-only layer for the (still-unrouted) `BookComparison.tsx` grid. Never touches
the grade path.

- `GET /api/books/:sport/:player/:stat?side=over|under` → the honest per-prop
  grid: `{ player, stat, line, side, books:[{book,line,over_odds,under_odds,
  isBest}], bestBook, bestOdds, bookCount, savings, crowned }`. HONEST-ABSENT:
  a single-book prop returns that one book with `isBest:false, bestBook:null,
  crowned:false` — never a placeholder second row. `:player` is matched by
  `nameKey` (accent/dot/nickname-folded).
- `GET /api/books/:sport?side=&limit=` → "best lines tonight" (`bestLines`, sorted
  by savings). This is a CROWN claim, so it returns `[]` while the crown is gated
  off. Response `source` = `bookprices` (snapshot-locked store serving) or
  `odds-cache` (fallback before first snapshot) — also the deploy fingerprint.
- **The crown is threshold-gated + OFF by default** (`BOOK_CROWN_ENABLED=1` to
  enable). Pre-registered gate: median same-line spread ≥8¢ OR ≥2 implied-prob
  pts (`scripts/measure-book-spread.js`). Measured 2026-07-27 on the live feed:
  MLB median 5¢/0.95pp, WNBA 7¢/1.38pp → NOT met → crown does NOT ship. Render
  books WITHOUT crowning one until a future measurement clears the bar.
- Source store: `bookprices:{sport}` (Redis, SNAP_TTL), written by
  `snapshotService` from the pre-dedup multi-book `props`. Grouped
  `{player, stat_type, books:[...]}`, normalized-name-keyed. DISPLAY-ONLY —
  fenced from grade/selector/challenger/ledger.