Contact-quality challenger (contact-v1) — nominate, don't swap

Phase A #2: the champion grade (l5/l20 result-based form) is a HYPOTHESIS that
contact quality predicts better — unmeasured on our props, with zero settled
p_win yet. Swapping l5/l20 (the champion's two heaviest ±1.0 factors) blind
could degrade the core grade undetectably for weeks. So this NOMINATES contact
quality as a second challenger, records what it WOULD project per prop, and lets
the settled ledger decide. Nothing users see changes; the champion is untouched.

- src/services/contactChallenger.js — pure, mirrors challengerProjection. Log-
  odds lean (capped, never a re-forecast) from SEASON contact quality vs league
  percentiles. Metric→prop mapping is the whole game: barrel_pct→HR,
  hard_hit_pct→TB/doubles, k_pct-INVERSE→hits (singles resolve on contact
  frequency, not barrels), k_pct→batter K. rbi/runs/walks ABSTAIN (opportunity/
  discipline — no clean contact predictor). Honest-absent: thin (<50 PA)/absent/
  unmapped/non-batter → p_win_contact NULL (no projection), never a fallback;
  "measured but unremarkable" is distinct (equals champion, delta 0).
- Wired in snapshotService AFTER arch-v1, reusing the already-loaded statcast
  rows; its own try so a second challenger can't break the pipeline. Reads
  g.p_win, never writes it.
- Retained SEPARATELY on the ledger (p_win_contact/contact_delta/
  contact_adjustments/contact_version='contact-v1') so each challenger's marginal
  contribution is measured independently; ledger_entries.stat gives per-prop-type
  segmentation. Migration 031 (applied to prod).

Phase 0 (prod-verified): statcast_aggregates is SEASON cumulative (not rolling),
48h stale now but season-scoped so ~8 PA/600 is negligible; 100% of graded
hitters covered, 92% at ≥50 PA; no xBA/xwOBA in the feed. Forward-only,
version-stamped (contact_version null on pre-nomination rows). Promotion is a
LATER decision on settled evidence, per prop type — never asserted here.

contactChallenger 14/14; snapshot/ledger/arch-v1 suites 80 green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VCNgGSt5qvcLxaeQqa7Zpj

src/services/contactChallenger.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * CONTACT-QUALITY CHALLENGER (Phase A #2) — a SECOND challenger, nominated not
+ * swapped. The champion grade (l5/l20 result-based form → `p_win`) is READ,
+ * never written. This computes a separate probability from SEASON contact
+ * quality (Statcast) and retains it beside the champion and the arch-v1
+ * challenger, so the settled ledger — not belief — decides whether contact
+ * quality beats result-based form, PER PROP TYPE.
+ *
+ * ── DISTINCT FROM arch-v1, ON PURPOSE ────────────────────────────────────
+ * The archetype challenger (`challengerProjection`, `arch-v1`) writes
+ * `p_win_challenger`. This writes `p_win_contact` under `contact-v1`. Kept
+ * SEPARATE so each challenger's marginal contribution is measurable on its own
+ * — folding contact into arch-v1 would contaminate a clean A/B.
+ *
+ * ── SEASON, NOT RECENT ───────────────────────────────────────────────────
+ * `statcast_aggregates` is per-season cumulative (refreshed nightly), so this
+ * is a season contact-quality signal — a challenger to the season baseline,
+ * not a rolling recent-form window. Because it is a season aggregate it is
+ * robust to a day or two of ingestion lag (~8 PA out of 600+ moves nothing).
+ *
+ * ── METRIC → PROP MAPPING IS THE WHOLE GAME ──────────────────────────────
+ * Contact metrics are NOT interchangeable across prop types. Barrels predict
+ * HOME RUNS and TOTAL BASES; they say little about SINGLES. A "hits over 0.5"
+ * prop resolves mostly on contact FREQUENCY, so it reads k_pct (inverse), not
+ * barrels. A wrong mapping degrades the model while looking sophisticated, so
+ * only mechanically-defensible pairs are encoded — opportunity stats (rbi /
+ * runs) and pure-discipline stats (walks) ABSTAIN rather than guess.
+ *
+ * ── HONEST-ABSENT ────────────────────────────────────────────────────────
+ * No coverage, thin sample (< MIN_PA), an unmapped stat, or a non-batter
+ * profile → the challenger returns NO projection (`p_win_contact === null`),
+ * never a silent fallback to a different signal. An abstention is data; a
+ * fallback corrupts the comparison. "Measured but unremarkable" (mid-pack
+ * metric) is DIFFERENT: it is a real no-lean projection equal to the champion.
+ *
+ * ── ISOLATION ────────────────────────────────────────────────────────────
+ * `contactAdjust()` is pure — same inputs, same output, no I/O, no shared
+ * state. The nudge is applied in LOG-ODDS space (a lean, never a re-forecast)
+ * and capped, so it can neither run away nor push a probability past 0/1.
+ */
+
+const CONTACT_VERSION = 'contact-v1';
+
+/** Below this plate-appearance sample the contact metric is too thin to trust
+ *  → honest abstention (no projection), matching the harness's refusal rule. */
+const MIN_PA = Number(process.env.CONTACT_MIN_PA) || 50;
+
+/** Log-odds nudges. `elite` = league p90+ favorable, `hi` = p75+. Small — a
+ *  lean on a real signal, not a re-forecast. Capped by MAX_NUDGE. */
+const NUDGE = Object.freeze({ elite: 0.22, hi: 0.11 });
+const MAX_NUDGE = Number(process.env.CONTACT_MAX_NUDGE) || 0.30;
+
+/**
+ * stat → { metric, sign }. sign +1 = a HIGHER metric means MORE of the stat;
+ * -1 = a higher metric means LESS. Only mechanically-defensible pairs. Stats
+ * absent from this map ABSTAIN (rbi/runs = opportunity-driven; walks =
+ * discipline; every pitcher stat = wrong role).
+ */
+const STAT_METRIC = Object.freeze({
+  home_runs:   { metric: 'barrel_pct',   sign: +1 }, // a barrel IS a home run
+  total_bases: { metric: 'hard_hit_pct', sign: +1 }, // hard contact → extra bases
+  doubles:     { metric: 'hard_hit_pct', sign: +1 },
+  triples:     { metric: 'hard_hit_pct', sign: +1 },
+  hits:        { metric: 'k_pct',        sign: -1 }, // singles resolve on CONTACT — low K = more balls in play
+  strikeouts:  { metric: 'k_pct',        sign: +1 }, // batter strikeout prop
+});
+
+const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+const toLogOdds = (p) => Math.log(p / (1 - p));
+const fromLogOdds = (l) => 1 / (1 + Math.exp(-l));
+
+function num(v) {
+  if (v == null || v === '') return null;
+  const n = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** percentileOf(sortedAsc, x) — fraction of the reference below x, 0..1. */
+function percentileOf(sortedAsc, x) {
+  if (!sortedAsc || !sortedAsc.length) return null;
+  let lo = 0; let hi = sortedAsc.length;
+  while (lo < hi) { const m = (lo + hi) >> 1; if (sortedAsc[m] < x) lo = m + 1; else hi = m; }
+  return lo / sortedAsc.length;
+}
+
+/**
+ * buildRefs(rows) — PURE. league reference distributions (sorted ascending) for
+ * each mapped metric, from sufficient-sample BATTERS only. Percentile-anchored,
+ * so no magic league-average constants and the tiers adapt to the real slate.
+ */
+function buildRefs(rows) {
+  const refs = {};
+  const metrics = new Set(Object.values(STAT_METRIC).map((m) => m.metric));
+  for (const metric of metrics) {
+    const vals = [];
+    for (const r of rows || []) {
+      if (!r || r.role !== 'batter') continue;
+      const pa = num(r.sample_pa);
+      if (pa == null || pa < MIN_PA) continue;
+      const v = num(r[metric]);
+      if (v != null) vals.push(v);
+    }
+    vals.sort((a, b) => a - b);
+    refs[metric] = vals;
+  }
+  return refs;
+}
+
+/**
+ * contactAdjust({ pWin, direction, statType, row, refs }) — PURE.
+ * Returns { p_win_contact, contact_delta, contact_adjustments, reason, version }.
+ *  - p_win_contact === null  → ABSTAINED (no usable input). NOT a projection.
+ *  - p_win_contact === pWin  → measured but unremarkable (real no-lean).
+ *  - otherwise               → a real contact-quality lean.
+ */
+function contactAdjust({ pWin, direction, statType, row, refs } = {}) {
+  const p = num(pWin);
+  // ABSTAIN: no projection made (null), distinct from a no-lean equal-to-champ.
+  const abstain = (reason) => ({
+    p_win_contact: null, contact_delta: null, contact_adjustments: null, reason, version: CONTACT_VERSION,
+  });
+  // NO LEAN: measured, mid-pack → a real projection that equals the champion.
+  const noLean = (reason) => ({
+    p_win_contact: p, contact_delta: 0, contact_adjustments: null, reason, version: CONTACT_VERSION,
+  });
+
+  if (p == null || p <= 0 || p >= 1) return abstain('no_champion_probability');
+  const stat = String(statType || '').toLowerCase();
+  const map = STAT_METRIC[stat];
+  if (!map) return abstain('stat_not_mapped');              // rbi/runs/walks/pitcher props
+  if (!row || row.role !== 'batter') return abstain('no_batter_profile');
+  const pa = num(row.sample_pa);
+  if (pa == null || pa < MIN_PA) return abstain('thin_sample'); // honest-absent, NO fallback
+  const v = num(row[map.metric]);
+  if (v == null) return abstain('metric_absent');
+  const sorted = refs && refs[map.metric];
+  if (!sorted || !sorted.length) return abstain('no_reference');
+
+  const pct = percentileOf(sorted, v);                      // player's league percentile
+  // goodness: 1 = best contact FOR THIS STAT. Inverse metrics (k_pct on hits) flip.
+  const goodness = map.sign > 0 ? pct : 1 - pct;
+
+  let mag = 0; let tier = null;
+  if (goodness >= 0.90) { mag = NUDGE.elite; tier = 'elite'; }
+  else if (goodness >= 0.75) { mag = NUDGE.hi; tier = 'hi'; }
+  else if (goodness <= 0.10) { mag = -NUDGE.elite; tier = 'poor'; }
+  else if (goodness <= 0.25) { mag = -NUDGE.hi; tier = 'lo'; }
+  else return noLean('metric_unremarkable');                // mid pack → no lean, equals champion
+
+  const dirSign = String(direction || 'over').toLowerCase() === 'under' ? -1 : 1;
+  const nudge = clamp(mag * dirSign, -MAX_NUDGE, MAX_NUDGE);
+  const challenger = clamp(fromLogOdds(toLogOdds(p) + nudge), 0.01, 0.99);
+  const rounded = Math.round(challenger * 1000) / 1000;
+
+  return {
+    p_win_contact: rounded,
+    contact_delta: Math.round((rounded - p) * 1000) / 1000,
+    contact_adjustments: [{
+      metric: map.metric, stat, tier,
+      value: Math.round(v * 100) / 100,
+      percentile: Math.round(pct * 100) / 100,
+      nudge: Math.round(nudge * 1000) / 1000,
+    }],
+    reason: null,
+    version: CONTACT_VERSION,
+  };
+}
+
+/**
+ * attachContactChallenger(grades, rowFor, refs) — map a slate's grades to the
+ * same grades PLUS the contact-v1 fields. `rowFor(playerName)` returns that
+ * hitter's statcast aggregate row (or null); injected so this does no I/O. The
+ * champion (`p_win`) and the arch-v1 fields are NEVER touched.
+ */
+async function attachContactChallenger(grades, rowFor, refs) {
+  const out = [];
+  for (const g of grades || []) {
+    if (!g) { out.push(g); continue; }
+    const row = typeof rowFor === 'function' ? rowFor(g.player || g.player_name) : null;
+    const res = contactAdjust({
+      pWin: g.p_win, direction: g.direction, statType: g.stat_type || g.stat, row, refs,
+    });
+    out.push({
+      ...g,
+      p_win_contact: res.p_win_contact,
+      contact_delta: res.contact_delta,
+      contact_adjustments: res.contact_adjustments,
+      contact_version: CONTACT_VERSION,
+      contact_reason: res.reason,
+    });
+  }
+  return out;
+}
+
+module.exports = {
+  contactAdjust,
+  attachContactChallenger,
+  buildRefs,
+  percentileOf,
+  CONTACT_VERSION,
+  STAT_METRIC,
+  MIN_PA,
+  NUDGE,
+};

src/services/ledgerService.js

@@ -255,6 +255,14 @@ function rowsFromSnapshot(sport, grades, oddsProps, nowIso) {
       challenger_delta: numOrNull(g.challenger_delta),
       challenger_adjustments: g.challenger_adjustments || null,
       challenger_version: g.challenger_version || null,
+      // Phase A #2 — the SECOND challenger (season contact quality), retained
+      // SEPARATELY from arch-v1 on the same row so both join to the same outcome
+      // and the same close. null p_win_contact = honest abstention (no
+      // projection), distinct from a no-lean equal-to-champion.
+      p_win_contact: numOrNull(g.p_win_contact),
+      contact_delta: numOrNull(g.contact_delta),
+      contact_adjustments: g.contact_adjustments || null,
+      contact_version: g.contact_version || null,
       // Session 75 — the ENVIRONMENT that drove this projection. The FORECAST,
       // not the actual: this is what we knew when we projected, and it is what
       // the instrument measures. The actual lands in game_context and is never

src/services/snapshotService.js

@@ -554,6 +554,22 @@ async function runSnapshot(sport, opts = {}) {
       const envMoved = withChallenger.filter((g) => g.env_multiplier != null).length;
       const platoonMoved = withChallenger.filter((g) => (g.challenger_adjustments || []).some((a) => a.axis === 'matchup')).length;
       console.log(`[challenger] ${sp} — ${moved}/${withChallenger.length} adjusted (env ${envMoved}, platoon ${platoonMoved})`);
+
+      // Phase A #2 — SECOND challenger: SEASON contact quality (contact-v1),
+      // tagged separately from arch-v1 so each is measured independently. Reuses
+      // the statcast rows already loaded; champion + arch-v1 fields untouched.
+      // Its own try — a second challenger must never break the pipeline either.
+      try {
+        const contact = deps.contactChallenger || require('./contactChallenger');
+        const refs = contact.buildRefs([...rowsByKey.values()]);
+        const rowForContact = (name) => rowsByKey.get(nameKey(name || ''));
+        withChallenger = await contact.attachContactChallenger(withChallenger, rowForContact, refs);
+        const cNudged = withChallenger.filter((g) => g.contact_delta).length;
+        const cAbstain = withChallenger.filter((g) => g.p_win_contact == null).length;
+        console.log(`[contact-challenger] ${sp} — ${cNudged} nudged, ${cAbstain} abstained / ${withChallenger.length}`);
+      } catch (e) {
+        console.warn(`[contact-challenger] ${sp} skipped:`, e.message);
+      }
     }
   } catch (e) {
     // The challenger must NEVER break the pipeline it is measured inside.