vyndr/specs/top-graded-selector.md

SPEC — /api/props/top-graded server selector (rank with p_win, serve without it)

Status: built 2026-07-29. New READ endpoint. No grade/ledger/lock_line/scoring write. Push scoring untouched. Spec companion: specs/grade-board-sort.md.

1. Review Zero findings

• 0.1 CORRECTED — the handler NEVER EXISTED. Not "removed": searched every commit (git rev-list --all) for a /top-graded definition in src/ — zero hits. The three axios callers (content/cheatsheetGenerator:21, content/gradeOfTheDay:17, routes/widget:76) and the Next proxy were written against a phantom endpoint, so those three content generators have silently received [] for their entire life. The contract is therefore recoverable ONLY from consumers, which is what this spec builds to.
• CONTRACT (VERIFIED, union of four consumers). Envelope { props: [...] } (all three callers do Array.isArray(res.data?.props); the Next proxy returns the same). Query: sport (UPPERCASE NBA|MLB|WNBA — the proxy validates that set; absent = all sports, which gradeOfTheDay relies on) and limit. Row fields REQUIRED by dashboard/page.tsx TopGrade: player, stat, line, direction ('over'|'under'), sport, grade, confidence?. Callers additionally read player_name || player, stat_type || stat, and game_id (cheatsheet's gameCount).
• 0.5 POPULATED-PATH RISK — FLAGGED. The board's populated branch has effectively never run in prod. dashboard/page.tsx:463 calls g.stat.replace(/_/g,' ') UNGUARDED — a row without a string stat THROWS and takes out the board. g.player is used in the key, the /scan URL and the <h3>; sport must be UPPERCASE (type Sport = 'NBA'|'MLB'|'WNBA', fed to SportPill). confidence is the only null-guarded field. The selector therefore emits player/stat as non-empty strings and uppercases sport, and DROPS any row that cannot satisfy that (a crashed board is worse than a shorter board).
• 0.2 VERIFIED — the strip can run server-side, after ranking. utils/requestTier.resolveTierFromRequest(req) is purpose-built for a PUBLIC endpoint (bearer token when present, else 'free') and FAILS CLOSED — any error returns the LEAST entitled tier, so a resolution failure can only withhold, never leak. utils/snapshotGating.stripModelPrice(rows, tier) deletes model_odds|p_win|ev_pct|value|takeable for unentitled tiers and stamps model_price_locked where a book+fair pair survives.
• 0.3 VERIFIED LIVE — the server HAS p_win right now. GET /api/hero-prop returns available:true (Brionna Jones, B, wnba), and the hero rule REQUIRES a non-null p_win AND a takeable price, so the snapshot cache carries both server-side. The public /api/snapshot shows p_win on 0/8 MLB + 0/25 WNBA rows only because it is stripped on the way out.
• 0.4 ONE SHARED DEFINITION. Extracted to src/utils/gradeRanking.js (takeablePWin, descNullsLast, rankGrades). heroPropService now imports takeablePWin instead of its inline copy, and the new selector imports rankGrades. The browser cannot import src/ (S25 rule), so web/src/lib/slateAdapter keeps its mirror — a test cross-checks the two on identical fixtures, the playerName.js precedent. Takeable band = config/valueEngine.isTakeable (−160..+200), strict-null.

2. The order of operations (the leak surface)

read snapshot cache  →  RANK with p_win (all tiers, server-side)
  →  map to contract rows INCLUDING model fields
  →  stripModelPrice(rows, tier)        ← the boundary
  →  serialize

Ranking happens BEFORE the strip, so a free caller gets the SAME order an entitled caller gets, without the paid values. Cache-Control follows the /api/snapshot precedent: private when a bearer token is present, public otherwise — a CDN must never hand a paid payload to an anonymous viewer.

3. Rank order

grade → confidence → takeable-gated p_win (nulls LAST) → SIGNED edge (nulls LAST) → stable input order. Grade-first because this is "top GRADES", not "top read" — it is INTENDED that this board and the hero can lead with different picks (the hero is p_win-first). They agree within the leading grade tier.

4. Acceptance criteria

1. Entitled request: ranked by takeable-gated p_win; p_win PRESENT in the payload.
2. Unentitled request: byte-identical ORDER; p_win/ev_pct/model_odds/value/ takeable ABSENT. Proven with POPULATED p_win, not today's nulls.
3. Nulls sort LAST server-side; untakeable chalk never tops the board.
4. Grade tier dominates every signal.
5. Thin/empty slate → 200 { props: [] }, never 404, never filler.
6. Every emitted row satisfies the populated-render contract (string player+stat, uppercase sport).
7. Hero / client / server use ONE definition — cross-checked by test.
8. No grade/ledger/lock_line/scoring write. Suite green, web build exit 0.

5. Held

edge_pct rescale or display retirement (Order B) · changing the board's columns or contract · making the board and hero lead with the same pick.