vyndr/specs/model-train.md

# MODEL TRAIN — VALUE ENGINE

**Status:** Arc 1 (steps 1–6) SHIPPED on main `7a925f4` (2026-07-19). Arcs 2+ OPEN.
**Written retroactively** (2026-07-19) per CLAUDE.md rule #1 — Arc 1 was built from a
plan that lived only in a session context that was lost. Everything in the "SHIPPED"
sections below was read off the code ON DISK, not from that plan or from memory.

**Doctrine (Kev):** VYNDR promotes bets people actually take — roughly the **−160 to
+200** band — that ALSO carry a genuine vig-free edge. Not plus-money-only, not heavy
chalk. *Grade* answers "is this a good read"; *value* answers "does the price pay you."
They are separate fields and must stay separate.

---

## 1. WHAT ARC 1 SHIPPED

### 1.1 De-vig — `src/utils/devig.js` (new)

Two-way **multiplicative** (proportional / normalized-implied-probability) de-vig.
Each side's implied probability is divided by the sum of both; the sum's excess over 1
is the `overround`. Method is recorded on the payload as `devig_method:'multiplicative'`.

| Export | Behavior |
|---|---|
| `americanToImpliedProb(a)` | `+`: `100/(a+100)`; `−`: `−a/(−a+100)`. Null on non-finite or `0`. |
| `americanToDecimal(a)` | Total-return multiple incl. stake. Null on non-finite or `0`. |
| `impliedProbToAmerican(p)` | Null outside `(0,1)`. `p>0.5` → negative (favorite). |
| `devigTwoWay(overOdds, underOdds)` | `{method, overround, over:{fair_prob,fair_odds}, under:{…}}`. **Returns `null` if EITHER side is missing/invalid** — fair values are never synthesized from one side. |
| `evPct(modelProb, american)` | `modelProb × decimal − 1`, as a percentage rounded to **one decimal**. Null on bad input. |

Rounding: probabilities/overround to 3 dp (`round3`); `ev_pct` to 1 dp.

### 1.2 Config knobs — the ACTUAL values on disk

**`src/config/valueEngine.js`** (new — the promotion gates):

| Knob | Env var | Default in code | Meaning |
|---|---|---|---|
| `TAKEABLE_ODDS_CEILING` | `TAKEABLE_ODDS_CEILING` | **−160** | Most-juiced favorite we will PROMOTE. |
| `TAKEABLE_ODDS_MAX` | `TAKEABLE_ODDS_MAX` | **+200** | Longest dog we will PROMOTE. |
| `VALUE_EV_THRESHOLD` | `VALUE_EV_THRESHOLD` | **2** (i.e. 2 % EV) | Minimum EV for the `value` flag. |

- `isTakeable(american)` → `a >= −160 && a <= +200`. **Strict**: `null`, `''`,
  `undefined`, and non-finite are `false` (the `Number(null)===0` fabrication trap).
- `isValue(american, evPct)` → `isTakeable(american) && Number.isFinite(evPct) && evPct >= 2`.

**`src/config/rareEventMarkets.js`** (pre-existing, from the same-day rare-event work —
the refusal layer that sits UNDERNEATH the promotion gates):

| Knob | Env var | Default in code | Meaning |
|---|---|---|---|
| `JUICE_ODDS_FLOOR` | `JUICE_ODDS_FLOOR` | **−400** | Graded side at or past this price → **refused, not graded**. |
| `RARE_EVENT_LINE_MAX` | — (constant) | **0.5** | Line at/below which the rare-event rules apply. |
| `RARE_EVENT_STATS` | — (constant) | `doubles, triples, home_runs, stolen_bases, steals, blocks` | Backup list for props with NO odds. |

**Knobs that DO NOT EXIST** (verified by grep across `src/`, `web/src/`, `tests/`):
`TAKEABLE_CEILING` (real name is `TAKEABLE_ODDS_CEILING`), `EDGE_FLEX_WALL`,
`HARD_JUICE_WALL`, `LADDER_ODDS_MAX`, `MIN_RUNG_PROBABILITY`. If those were in the
original plan, they are **unbuilt** — see §3.

### 1.3 What the gate ACTUALLY does today

Reported as-built, not as-designed. There are **two independent layers**, and only the
first one can refuse a grade:

**Layer A — the refusal wall (`JUICE_ODDS_FLOOR`, −400).** In `analyzeViaEngine1`, the
FIRST thing that happens — before `computeFeaturesForProp`, before any projection:

```
if (isTooJuiced(rawProp)) → suppressedRareResult('juiced_no_edge')
```

Characteristics of the shipped behavior:
- **A flat price wall, NOT edge-aware.** It looks only at the graded side's American
  price. No EV, no projection, no edge, no flex band participates in the decision.
- **The wall is −400, not −250.** There is no −250 constant anywhere in the codebase.
- It runs **pre-feature**, so a refused prop costs zero feature computation.
- Odds absent → `isTooJuiced` is `false` (can't judge from a price that isn't there);
  the structural `RARE_EVENT_STATS` rule is the backup for that case.
- Output is a refusal, not a bad grade: `grade:null`, `insufficient_data:true`,
  `suppressed:true`, `suppressed_reason:'juiced_no_edge'`, plus branded "No read —…"
  copy in `reasoning.summary`.

The other two refusals in the same family: `rare_event_under` (rare stat, under, line
≤ 0.5 — pre-feature, needs no projection) and `rare_event_over_below_line` (rare stat,
over, line ≤ 0.5, and the model does NOT project above the line — checked after the
projection exists).

**Layer B — the takeable band (−160 … +200).** This gate **never refuses a grade**.
It is a *promotion* filter, applied only where a read is featured:
- Today its ONLY enforcement point is `heroPropService.pickHeroProp`
  (`if (!isTakeable(g.book_odds)) continue`).
- Every graded read still carries `takeable` / `value` as flags for consumers.
- The full board shows every graded read regardless of band. Parlay Lab is exempt by
  design (juiced legs combine into takeable payouts).

So: **edge-aware promotion, price-only refusal.** The `-400` wall decides what gets
graded; EV + the `−160/+200` band decide what gets promoted.

### 1.4 The value triplet

Attached in `analyzeViaEngine1`'s existing p_win/Kelly `try` block (so it inherits the
"real quantile probability × real book odds, or nothing" rule, and the whole block is
additive — a throw never breaks the read):

| Field | Source | Absent when |
|---|---|---|
| `book_odds` | the graded side's actual price (`under_odds` if under, else `over_odds`) | no side odds |
| `fair_odds`, `fair_prob` | `devigTwoWay(over, under)` for the graded side | **either** side unpriced |
| `model_odds` | `impliedProbToAmerican(pWin)` | no quantile probability |
| `overround`, `devig_method` | from the de-vig | either side unpriced |
| `ev_pct` | `evPct(pWin, sideOdds)` | no pWin or no side odds |
| `takeable` | `isTakeable(sideOdds)` | no side odds |
| `value` | `isValue(sideOdds, ev)` | no ev |

The intended render (Design's, not built): *"book −145 · vig-free −132 · model −110."*

### 1.5 Hero v2 — `heroPropService`

Old rule: largest `|projection − line|` among A/B candidates. **New rule:** among A/B
candidates, keep only those with a finite `ev_pct` **and** a takeable `book_odds`, then
take the **highest `ev_pct`**. The `gap` is still computed and returned for display, but
it no longer selects. Empty-slate fallback (most recent real graded read, any grade, by
timestamp) is unchanged. `toHero` now also passes through
`ev_pct / value / takeable / book_odds / fair_odds / model_odds`.

### 1.6 Distribution + tests

- Fields ride the existing `...result` / `...data` spreads into `grades:{sport}`,
  `/api/snapshot/:sport`, `/api/hero-prop`, `/api/scan`. Documented in
  `BACKEND_HANDOFF.md` ("Value Engine fields").
- `src/utils/tierGating.js` deletes `alt_lines` (below Desk) and `kelly` (below the
  Kelly tier). It does **not** touch the value fields — `ev_pct`, `value`, `takeable`,
  and the triplet are currently visible to **every tier including free**. That is an
  unmade product decision, not a verified choice (see §3).
- Suite: **276 suites / 3306 tests**, green, `next build` exit 0. New:
  `tests/unit/devig.test.js`, `tests/unit/valueEngine.test.js`;
  `tests/unit/heroPropService.test.js` rewritten for the EV rule.

---

## 2. LAWS THIS TRAIN INHERITS (do not relax)

- **Absent beats wrong.** One side unpriced → `fair_odds` is absent, never
  extrapolated. No price → `takeable` is absent, not `false`-by-coercion.
- **`Number(null) === 0`** is the standing fabrication bug of this codebase. Every new
  numeric path gets a strict guard (`valueEngine.isTakeable` is the model).
- **Grade ≠ value.** An A read with `value:false` is honest output: right read, price
  gone. Never let the value flag re-letter a grade.
- **Refusal is a product surface**, not an error. Refused reads carry branded copy.
- Market values are REAL book numbers at a timestamp; only projection / grade / edge /
  EV / fair price are model output and must be labeled MODEL.

---

## 2B. FOUNDATION-FIRST RE-ORDER (Kev, 2026-07-19) — supersedes the arc order

New features are paused until the foundation is real. Phases run in order:
1 (tooling+safety) → 2 (the instrument) → 3 (corruption fixes) → 4 (depth).

| # | Item | Phase | Status |
|---|---|---|---|
| 1 | Manual regrade trigger | 1 | ✅ `scripts/run-snapshot.js` shipped — **but see ACCESS BLOCKER** |
| 2 | Backup cron INSTALLED | 1 | ✅ shipped as CODE (`src/backupScheduler.js`) — deploy == installed |
| 3 | Backtest harness | 2 | open — REPORT-FIRST on replayable history |
| 4 | Settlement-correctness audit | 2 | open — REPORT |
| 5 | Sample-size discipline | 2 | open — report the floor |
| 6 | edge_pct → ev_pct migration | 3 | open — REPORT-FIRST (ledger bleed) |
| 7 | Grade-lock + directional CLV + C4 | 3 | open — REPORT-FIRST (does a snapshot overwrite a prior grade?) |
| 8 | Model uncertainty | 4 | open — REPORT-FIRST (design proposal) |
| 9 | Calibration by odds band | 4 | open — runs ON the harness |

### 🔴 ACCESS BLOCKER (Session 64) — I cannot reach the box

Verified this session: **no `VYNDR_INTERNAL_KEY` in the local `.env`** (it holds
only Supabase + `ODDS_API_KEY`), and **SSH to `git.builtbykev.com` /
`api.vyndr.app` / `vyndr.app` times out from WSL2.** So I can neither call the
internal endpoints that already exist (S45 shipped
`POST /api/internal/snapshot/:sport|/all`) nor `docker exec` anything.

Consequences, stated plainly:
- The manual trigger is BUILT and correct, but **only Kev can run it** until one
  of these exists: `VYNDR_INTERNAL_KEY` shared with the agent env, or box SSH.
- Verifying a grading fix still depends on the cron or on Kev running one command.
- **This is the single highest-leverage unblock for every future phase** — Phase 2
  and 3 both need on-demand regrade + settle runs to verify anything.

### Standing cautions (Kev, logged 2026-07-19)

- **CLV ledger stays PRIVATE** until the model is backtest-proven. Publishing CLV
  before then broadcasts our weaknesses to sharps. (Also currently broken — C4.)
- **"Self-improving model" is UNSUPPORTED marketing** until the loop actually
  closes: backtest → calibration → weight correction. No such loop exists today
  (no harness, no calibration gate, `weightAdjuster` is not in the grade path).
  Do not claim it.
- **The engine is MLB/WNBA-calibrated. NFL/NBA/soccer are NOT.** "Unified engine"
  is currently "MLB engine, others guessing." Each sport needs its own calibration
  before the offseason hub grades it — this is a **scaling gate**, not a nice-to-have.

## 2A. ARC 2+ BOARD — STATUS (Kev's arc list, 2026-07-19)

Full arc definitions live in the Session-63 order. Status only here; update as each ships.

| Item | Status | Note |
|---|---|---|
| **G-a** the real gate | **HELD for ruling** | Built nothing yet — the G-b report changes the recommended dials. See `specs/audit-data/gate-simulation.md` §2.4. |
| **G-b** gate simulation | ✅ **REPORTED** | `specs/audit-data/gate-simulation.md`. Replayed over the ledger, NOT snapshots (no 30d snapshot store exists). |
| **G-c** never-empty honesty | open | Rare but real on thin MLB nights. |
| **S-a** line-moved truth | open | Shares plumbing with C-clv — build together. |
| **S-b** board ranks on EV | open | Blocked-ish: EV not persisted; live payload has it. |
| **L-a** per-rung odds? | ✅ **REPORTED — NO** | Rungs are synthetic, carry no price. Feed offers no alternate markets. §3 of the report. |
| **L-b** per-rung EV ladder | **BLOCKED** | Needs a real price per rung. Probe PropLine first. |
| **C-cal** calibration | ✅ **REPORTED** | Confidence monotonic but ~20-25pts miscalibrated; **only B/C grades ever emitted**. |
| **C-led** ledger speaks value | open — **recommended next** | `locked_odds` already 99.1% populated: units/ROI need no backfill. EV columns are net-new, forward-only. |
| **C-clv** fix C4 | open | Confirmed broken in data (359/376 MLB closes == lock). Keep suppressed. |
| **D-ref** visible refusals | partial | Copy already ships on refusals; new `gate_*` reasons land with G-a. |
| **D-par** parlay lab | open | Gate must NOT apply inside the Lab. |
| **D-tier** tier gating | **DECIDED, not enforced** | Free/Analyst: value marker + grade + triplet. Desk: ladder + per-rung EV + Kelly. Today ladder/Kelly are already Desk-gated; triplet ungated = correct per this ruling. |
| **D-ev** consolidate EV | open | `devig.evPct` vs `processing/EVCalculator.js` (used only by `UnifiedOddsProvider`). |
| **U-deg** MLB degradation | ✅ **STATUS REPORTED** | `projection==0` leak **already closed** (0 occurrences since 07-18). `edge_pct` scale still broken. |
| **U-fp** Arc 1 fingerprint | open | Do it on the first deploy this train ships. |

### ✅ SESSION 63 — PROBABILITY LAYER + GRADE RANGE RESTORED (shipped)

The re-sequenced step 1+2, folded into one change. Full write-up:
`specs/audit-data/grade-collapse.md`.
- **The probability layer was DEAD in production** — `p_win`/`ev_pct`/`kelly`/
  `model_odds`/`value` were absent on 0/8 live grades because `gameLogService`
  returns null for MLB by construction and the Python service is offline for
  NBA/WNBA. `featureCache.getStatRows` now supplies normalized rows for every
  sport. **Verified: `p_win` 25/25 on real WNBA props, 8/8 MLB (was 0).**
- **Hero v2 had never once selected on EV** (it requires a finite `ev_pct`) and
  silently fell through to the recent-read fallback every time.
- **Grade range:** `refreshTeamStats` wired into `runSnapshot` (it had ZERO
  callers, so `opp_rank_stat` was permanently null), `game_count_in_7d` derived
  from real logs, and **L20 made symmetric** (there was no negative branch at
  all). D now emits on merit (WNBA 1/25, an earned `p_win` 0.365); A is proven
  reachable arithmetically but **has not yet emitted in production — that is the
  outstanding fingerprint**.
- **Calibration guard:** consistency CV was NBA-tuned; for any stat with mean < 4,
  `cv ≈ 1/√mean` forces `boom_bust`. It would have stamped a blanket −1.0 on
  nearly every MLB prop. Floored at `CONSISTENCY_MIN_MEAN=4` → `unknown` below it.
- **Confidence is NOT a probability** — payloads now carry
  `confidence_basis: 'grade_band'`. The real signal is `p_win`.
- **`mlbGrader.js` REMOVED** (dead; referenced only by its own test).
- 🔴 **MARKETING HOLD:** "A-RATED" copy (AccuracyBadge, TopSignals) is unsupported
  until a production fingerprint shows real A grades. Honest fallbacks confirmed
  rendering ("MODEL · 63% HIT"); nothing fabricated ships.

### 🔶 OPEN DECISION — FLEX BAND ENFORCEMENT (Kev, 2026-07-19)

**Ruling:** build `EDGE_FLEX_WALL` (−250) + `EV_FLEX_THRESHOLD` (default **4 %**, = 2×
`VALUE_EV_THRESHOLD`) but ship with **`EV_FLEX_ENFORCE=0`**. Flex-band props
(−161…−250) **grade exactly as they do today — the band is NOT cut.** The ledger shows
it is our most profitable segment (**+2.2 % ROI, n=70**) and we will not restrict a
proven-profitable band on an unvalidated threshold. Record `ev_pct` on every flex prop
now so real in-production data accumulates.

**TRIGGER TO REVISIT:** once ~2 weeks of production `ev_pct` data exists on the
−161…−250 band, report the **`ev_pct` distribution vs settled outcomes for that band**,
then Kev decides the threshold — or whether to enforce at all.
**Do NOT flip `EV_FLEX_ENFORCE=1` without that report and explicit sign-off.** It comes
back as a data-backed decision, never a silent flip.

**Unaffected — these ship and enforce normally:** `HARD_JUICE_WALL` (−250, never grades),
`LADDER_ODDS_MAX` (+400), `MIN_RUNG_PROBABILITY` (0.25), the no-odds refusal, and the
folded `projection > 0` check.

### 🔴 OPEN — U-deg PART 2: `edge_pct` IS ON A BROKEN SCALE (next U-deg item)

`projection == 0` is closed. **`edge_pct` is not**, and it is the one still being
read by users. Live proof from the S63 fingerprint response: `edge_pct: 100` on a
prop whose real edge is single-digit. Ledger-wide: **311/604 rows (51.5 %) exceed
`EDGE_BOARD_SANE_MAX` (40), 39 rows exceed 100 (impossible as a percentage), worst
620.**

**Who reads what — this is the problem in one line: every user-facing surface reads
the broken number, and nothing reads the good one.**

| | Consumers |
|---|---|
| **`edge_pct` (BROKEN)** — frontend | `Slate.tsx`, `PropRow.tsx`, `GradeCard.tsx`, `GradeResultCard.tsx`, `MobileEdgeBoard.tsx`, `TierRecord.tsx`, `DemoScan.tsx`, `SoccerGradeResult.tsx`, `slateAdapter.js`, `gradeAdapter.js`, `scan/page.tsx`, `soccer/page.tsx`, `api/scan/route.ts` |
| **`edge_pct` (BROKEN)** — backend | `deskShowcaseService`, `contentTemplateService`, `parlayScanService`, `tierGating` (free-tier "hook"), **`ledgerService:199` → persists it to the `edge` column** |
| **`ev_pct` (GOOD)** — frontend | **NONE** |
| **`ev_pct` (GOOD)** — backend | `heroPropService` only |

Consequences to fix together, not piecemeal:
1. The frontend's `EDGE_BOARD_SANE_MAX = 40` guard is **damage control that nulls
   half the board** — it hides the bug rather than fixing it.
2. `ledger_entries.edge` is being written with garbage **right now**, permanently,
   into an append-only table. Any future edge-based analysis inherits it.
3. **S-b (rank board on EV) is the real remedy** — it moves ranking off `edge_pct`
   onto `ev_pct`, which is now live and correct. Do S-b and the edge-scale fix as
   one piece of work.
4. Free tier is sold `edge_pct` as "the hook" (`tierGating:62`). That hook is
   currently a wrong number.

### 🔶 OPEN — INDEX-OF-DISPERSION CONSISTENCY CLASSIFIER (modelling change)

`CONSISTENCY_MIN_MEAN = 4` is an **honest stopgap, not the answer.** It stops the
NBA-tuned CV thresholds from stamping `boom_bust` on every low-count MLB stat
(`cv ≈ 1/√mean`, so mean < 4 always trips `boom_bust`) — but the cost is that MLB
low-count stats get **no consistency factor at all**, leaving a ±1.0 dead for the
sport that carries most of our volume.

**The real fix:** classify on the **index of dispersion** (variance / mean) against
the Poisson baseline of 1.0 — under-dispersed (< 1) = genuinely consistent,
over-dispersed (> 1) = genuinely boom/bust. It is scale-free, so one set of
thresholds works for MLB hits (mean 0.6) and NBA points (mean 20) alike.

**VALIDATION REQUIRED BEFORE IT SHIPS** — this changes grades, so per the standing
rule no weight change ships without a backtest:
1. Build the backtest harness (still does not exist — see below).
2. Replay settled outcomes with dispersion-based consistency vs the current floor.
3. Show hit-rate/ROI by grade tier does not degrade, and that the restored ±1.0
   moves grades on merit rather than flooding one letter.
4. Report before flipping. Env-gate the switchover.

### Backtest harness
**None exists** (grep-verified). `migrations/006` defines `grade_outcomes` +
`player_calibrated_weights` and **no code reads or writes them**. The G-b/C-cal replay was
done in SQL against `ledger_entries`; a real harness is still owed before any weight change.

## 3. NOT YET BUILT — checklist to reconcile against the full arc list

Verified absent from the codebase as of `7a925f4`. Kev supplies the complete arc list;
mark each done/open against this.

**Engine / gates**
- [ ] Edge-aware juice wall — a soft/flex band where a big enough edge can survive a
      juiced price (`EDGE_FLEX_WALL`, `HARD_JUICE_WALL` — neither exists; today's wall
      is the single flat `JUICE_ODDS_FLOOR` −400).
- [ ] `TAKEABLE_ODDS_*` enforced on any surface beyond the daily hero (featured rows,
      top-of-board, alerts). Today: hero only.
- [ ] Alt-line ladder value gates (`LADDER_ODDS_MAX`, `MIN_RUNG_PROBABILITY` — neither
      exists). The ladder in `analyzeViaEngine1` is still the S62 build: fixed shifts
      `[−1, −0.5, 0, +0.5, +1]`, filtered to `line > 0`, sorted by `edge_pct`. It has
      **no odds ceiling and no per-rung probability floor**, and its rungs carry no
      `ev_pct` / `fair_odds` / price at all.
- [ ] EV-rank the board itself. `slateAdapter.flattenToEdgeBoard` still ranks on
      `edge` (guarded by `EDGE_BOARD_SANE_MAX = 40`), not `ev_pct`.
- [ ] Reconcile the orphan `src/services/processing/EVCalculator.js` (a separate,
      older EV path used only by `UnifiedOddsProvider`) against `devig.evPct` — two EV
      implementations currently coexist.
- [ ] Multi-way / three-way de-vig, and alternatives to multiplicative (Shin,
      power/log). Two-way multiplicative is the only method implemented.
- [ ] Best-price de-vig across books (today the triplet de-vigs whichever single
      book's two-sided price came through on the prop).

**Surfaces (nothing on the frontend reads these fields yet — grep-verified zero hits
for `ev_pct` / `fair_odds` / `model_odds` / `book_odds` / `suppressed_reason` under
`web/src/`)**
- [ ] Value triplet rendered on the reveal card / board row / hero.
- [ ] VALUE marker (and the honest "A but no value" state).
- [ ] Visible-refusal moment — the "No read —…" copy is generated and shipped on the
      payload but is not displayed anywhere.
- [ ] EV shown as the headline number instead of / alongside edge %.

**Product / policy**
- [ ] Tier policy for the value fields — currently ungated to free (§1.6).
- [ ] Alerts on takeable +EV reads (the config comment anticipates "future alerts").
- [ ] Ledger/record split by `value` (does the model's +EV subset beat its overall
      record?). `ledger_entries` stores no EV or fair price today.
- [ ] Settlement/CLV interaction with fair price — CLV is still locked-vs-closing
      LINE, not vs closing FAIR price. (Note: **C4 — CLV capture is broken** and
      suppressed on public surfaces; see `specs/audit-data/clv-capture-broken.md`.
      Any fair-price CLV work is blocked behind C4.)

**Verification debt**
- [ ] Arc 1 is **not deploy-fingerprinted**. Post-deploy, confirm `/api/hero-prop`
      returns a hero with a takeable `book_odds` and a finite `ev_pct`, and that
      `/api/snapshot/mlb` grades carry the triplet.
- [ ] Known upstream contamination: **`specs/audit-data/mlb-grade-degradation.md`** —
      projection == 0 on ~9/25 MLB grades and a broken `edge_pct` scale. EV is
      computed from the quantile probability, not from `edge_pct`, so it is not
      directly poisoned — but hero ranking and any EV-vs-edge comparison sit on top of
      that pipeline. Fix the degradation before trusting arc-1 numbers in aggregate.

---

*Arc 1 recorded 2026-07-19 from the code at `7a925f4`. Update this file in the same
commit as any arc that ships.*