Sessions 7e+7f: Grade adapter, normalize consolidation, computeFeatures, analyzeViaEngine1, scan/parlay migrated to engine1

src/routes/analyze.js

@@ -1,4 +1,13 @@
 const express = require('express');
+// ARCH-1 ESCAPE HATCH (Session 7f): /api/analyze stays on the legacy
+// analyzeProp path. The unification's adapter + computeFeatures +
+// analyzeViaEngine1 helpers are built and tested, but the integration
+// test for this route asserts specific grade VALUES that the legacy
+// engine produced for specific input mocks. Swapping in engine1
+// preserves the SHAPE (verified) but produces different VALUES because
+// the engine logic is intentionally different. Per the session rule
+// "tests pass unmodified", reverted. See docs/SYSTEM-MANIFEST.md §8
+// ARCH-1 for the migration roadmap.
 const { analyzeProp } = require('../services/propAnalyzer');
 const { cacheGet, cacheSet } = require('../utils/redis');
 const { createRateLimit } = require('../middleware/rateLimit');
@@ -11,7 +20,7 @@ const router = express.Router();
 const analyzeLimit = createRateLimit({ windowMs: 60_000, max: 10 });
 router.use(analyzeLimit);
 
-// PERF-1 (Session 7d): cache analyzeProp results in Redis. Same prop hit
+// PERF-1 (Session 7d): cache analyze results in Redis. Same prop hit
 // twice within 60s reuses the previous analysis instead of re-doing the
 // upstream chain. 60s is short enough that line moves still surface.
 const ANALYZE_TTL_SECONDS = 60;

src/services/intelligence/analyzeViaEngine1.js

@@ -0,0 +1,248 @@
+/**
+ * analyzeViaEngine1 — the canonical single-prop analysis function.
+ *
+ * Composes the three pieces sessions 6c, 7e, and 7f built:
+ *   computeFeaturesForProp → engine1.gradeProp → toLegacyShape
+ *
+ * Output matches the legacy `analyzeProp()` shape byte-for-byte (DemoScan
+ * + GradeCard read the same fields). The `reasoning.summary` here is built
+ * from real feature values (l5_avg, opp_rank_stat, etc.) so users still
+ * see concrete sentences, not abstract factor labels.
+ *
+ * Never throws. Every upstream failure mode is reflected as low-confidence
+ * grade + an explanatory reasoning summary.
+ */
+
+const { computeFeaturesForProp } = require('./computeFeatures');
+const engine1 = require('./engine1');
+const { toLegacyShape } = require('../../utils/gradeAdapter');
+
+// Map an error code from computeFeaturesForProp.meta.errors into a human
+// sentence the user will see in reasoning.summary.
+const ERROR_EXPLANATIONS = Object.freeze({
+  player_not_found_in_id_map: "We couldn't find this player in our roster index.",
+  no_game_scheduled_today: "No game scheduled for this player tonight.",
+  no_features_computed: "Statistical features unavailable for this player tonight.",
+});
+
+function explainErrors(errors) {
+  if (!Array.isArray(errors) || errors.length === 0) return '';
+  return errors.map((e) => ERROR_EXPLANATIONS[e] || `Data gap: ${e}.`).join(' ');
+}
+
+// Build a human-readable reasoning summary + steps from the actual
+// features (which carry real numbers) and engine1's grade.
+function buildConcreteReasoning(features = {}, engine1Result = {}, meta = {}, prop = {}) {
+  const lines = [];
+
+  // Recent form vs the line — L5 and L20 are the orchestrator's
+  // canonical season-trend signals.
+  if (Number.isFinite(features.l5_avg)) {
+    lines.push(`${prop.player || 'Player'} is averaging ${features.l5_avg.toFixed(1)} ${prop.stat_type || ''} over his last 5 games.`);
+  }
+  if (Number.isFinite(features.l20_avg)) {
+    lines.push(`Last 20 games average: ${features.l20_avg.toFixed(1)}.`);
+  }
+
+  // Trend direction relative to the line.
+  if (Number.isFinite(features.l5_avg) && Number.isFinite(prop.line)) {
+    const diff = features.l5_avg - prop.line;
+    if (Math.abs(diff) >= 0.5) {
+      const dir = diff > 0 ? 'above' : 'below';
+      lines.push(`That's ${Math.abs(diff).toFixed(1)} ${dir} the line of ${prop.line}.`);
+    }
+  }
+
+  // Home / away.
+  if (features.home_away === 1.0) lines.push('Playing at home tonight.');
+  else if (features.home_away === 0.0) lines.push('Playing on the road tonight.');
+
+  // Opponent matchup. opp_rank_stat is 0..1 normalized
+  // (0 = best D, 1 = worst D) — translate to friendlier language.
+  if (Number.isFinite(features.opp_rank_stat) && meta.opponentAbbr) {
+    if (features.opp_rank_stat >= 0.7) {
+      lines.push(`${meta.opponentAbbr} is a bottom-tier defense vs this stat.`);
+    } else if (features.opp_rank_stat <= 0.3) {
+      lines.push(`${meta.opponentAbbr} is a top-tier defense vs this stat.`);
+    } else {
+      lines.push(`${meta.opponentAbbr} is a middling defense vs this stat.`);
+    }
+  }
+
+  // Rest / fatigue context.
+  if (features.rest_days === 0) lines.push('Back-to-back — fatigue concern.');
+  else if (Number.isFinite(features.rest_days) && features.rest_days >= 2) {
+    lines.push(`${features.rest_days} days of rest.`);
+  }
+  if (Number.isFinite(features.game_count_in_7d) && features.game_count_in_7d >= 4) {
+    lines.push(`Heavy workload — ${features.game_count_in_7d} games in the last week.`);
+  }
+
+  // Injury context.
+  if (Number.isFinite(features.injury_severity_score) && features.injury_severity_score > 0) {
+    lines.push(`${features.injury_severity_score} opponent starter(s) on the injury report.`);
+  }
+
+  // Trap composite — surfaced when meaningful.
+  // (Adapter handles the per-factor kill_conditions chips; this line
+  // gives the user the overall warning.)
+  if (engine1Result?.grade && engine1Result.grade.endsWith('-') === false
+      && Array.isArray(engine1Result.all_factors)
+      && engine1Result.all_factors.includes('trap_composite_high')) {
+    lines.push('Multiple trap signals firing — proceed with caution.');
+  }
+
+  // Engine-1 verdict capper.
+  const grade = engine1Result?.grade;
+  if (grade) {
+    const verb = grade.startsWith('A') ? 'favors the play'
+      : grade.startsWith('B') ? 'leans toward the play'
+      : grade.startsWith('C') ? 'is split'
+      : 'leans against the play';
+    lines.push(`Engine 1 graded ${grade} — ${verb}.`);
+  }
+
+  // Tack on any data-gap explanations.
+  const gapNote = explainErrors(meta.errors);
+  if (gapNote) lines.push(gapNote);
+
+  const summary = lines.join(' ').trim()
+    || `Analysis complete. Grade: ${grade || 'C'}.`;
+
+  // Legacy-shaped steps so backward-compat callers (integration tests,
+  // anything pre-dating the engine swap) keep seeing the named
+  // sub-blocks. Each is populated from engine1 features where the data
+  // exists; missing sub-blocks contain null fields instead of being
+  // absent so callers can dot-access without optional chaining.
+  const seasonAvg = Number.isFinite(features.l20_avg) ? features.l20_avg : null;
+  const recentAvg = Number.isFinite(features.l5_avg) ? features.l5_avg : null;
+  const haContext = features.home_away === 1.0 ? 'home'
+    : features.home_away === 0.0 ? 'away' : null;
+  const restContext = features.rest_days === 0 ? 'b2b'
+    : Number.isFinite(features.rest_days) && features.rest_days >= 2 ? 'rested' : null;
+
+  return {
+    summary,
+    steps: {
+      season_avg: {
+        value: seasonAvg,
+        vs_line: seasonAvg != null && Number.isFinite(prop.line)
+          ? Math.round((seasonAvg - prop.line) * 10) / 10 : null,
+        signal: null,
+      },
+      recent_form: {
+        value: recentAvg,
+        vs_line: recentAvg != null && Number.isFinite(prop.line)
+          ? Math.round((recentAvg - prop.line) * 10) / 10 : null,
+        signal: null,
+      },
+      situational: {
+        home_away: { value: null, context: haContext, signal: null },
+        rest_days: { value: features.rest_days ?? null, context: restContext, signal: null },
+        vs_opponent: { value: null, games: null, signal: null },
+      },
+      line_comparison: {
+        best_line: null,
+        worst_line: null,
+        edge_from_best: 0,
+        signal: null,
+      },
+      kill_conditions: [],
+      final_grade: grade || null,
+      // Flat narrative bullets — kept under `steps` so legacy clients
+      // can still find them but they don't collide with the named
+      // sub-blocks above.
+      narrative: lines.map((line, i) => ({ step: i + 1, detail: line })),
+    },
+  };
+}
+
+// edge_pct in the legacy shape compares the relevant average to the line.
+// We use l5_avg when present (matches legacy "recent form" weighting),
+// fall back to l20_avg, otherwise return 0 so the field is always present.
+function edgePctFor(features, prop) {
+  const ref = Number.isFinite(features?.l5_avg) ? features.l5_avg
+    : Number.isFinite(features?.l20_avg) ? features.l20_avg
+    : null;
+  if (ref == null || !Number.isFinite(prop?.line) || prop.line === 0) return 0;
+  const signed = prop.direction === 'over' ? (ref - prop.line) : (prop.line - ref);
+  return Math.round((signed / prop.line) * 1000) / 10;
+}
+
+// When computeFeatures fails so badly that even a partial feature vector
+// is empty, return a legacy-shaped low-confidence result rather than
+// asking engine1 to grade nothing.
+function fallbackLegacyResult(rawProp, errors) {
+  return {
+    player: rawProp.player ?? null,
+    stat_type: rawProp.stat_type ?? null,
+    line: rawProp.line ?? null,
+    direction: rawProp.direction ?? null,
+    book: rawProp.book || 'unknown',
+    grade: 'C',
+    confidence: 10,
+    edge_pct: 0,
+    kill_conditions_triggered: [],
+    reasoning: {
+      summary: `Unable to compute full analysis. ${explainErrors(errors) || ''} Grade is provisional.`.trim(),
+      steps: [],
+    },
+  };
+}
+
+async function analyzeViaEngine1(rawProp = {}) {
+  const featureResult = await computeFeaturesForProp(rawProp);
+  const { features, trap, consistency, prop, meta } = featureResult;
+
+  // Hard fallback only when computeFeatures couldn't produce anything
+  // useful at all (no features AND no consistency input).
+  if ((!features || Object.keys(features).length === 0)
+      && (!consistency || consistency.consistency === 'unknown')
+      && (!Array.isArray(meta?.gameLogs) || meta.gameLogs.length === 0)) {
+    return fallbackLegacyResult(rawProp, meta?.errors);
+  }
+
+  // Engine 1: deterministic rule-based grade on the feature vector.
+  const engine1Result = engine1.gradeProp({ features, trap, consistency, prop });
+
+  // Translate engine1 output → legacy shape via the adapter from 7e.
+  // The adapter handles kill_conditions_triggered + the 4-letter grade
+  // collapse + the 0-100 confidence scale.
+  const summaryOverride = buildConcreteReasoning(features, engine1Result, meta, {
+    ...rawProp,
+    line: prop.line,
+  }).summary;
+
+  const legacy = toLegacyShape(engine1Result, {
+    player: rawProp.player,
+    stat_type: rawProp.stat_type,
+    line: prop.line,
+    direction: prop.direction,
+    book: rawProp.book || 'unknown',
+    sport: meta.sport,
+  }, {
+    summaryOverride,
+    edgePct: edgePctFor(features, prop),
+  });
+
+  // The adapter's reasoning.steps was a single-element debug bag;
+  // replace it with the line-by-line breakdown we built above so the
+  // legacy UI's step list looks identical to before.
+  legacy.reasoning = buildConcreteReasoning(features, engine1Result, meta, {
+    ...rawProp,
+    line: prop.line,
+  });
+
+  return legacy;
+}
+
+module.exports = {
+  analyzeViaEngine1,
+  __internals: {
+    buildConcreteReasoning,
+    edgePctFor,
+    fallbackLegacyResult,
+    explainErrors,
+    ERROR_EXPLANATIONS,
+  },
+};

src/services/intelligence/computeFeatures.js

@@ -0,0 +1,214 @@
+/**
+ * computeFeaturesForProp — the ONE permitted architectural addition of
+ * Session 7f. Bridges raw single-prop input (`{player, stat_type, line,
+ * direction, book, sport}`) to the feature-vector shape `engine1.gradeProp()`
+ * expects.
+ *
+ * The orchestrator does this same work inline, tied to its batch loop +
+ * grade_history persistence. This module lifts only the per-prop logic
+ * so single-prop callers (`/api/analyze/prop`, batch entries,
+ * `/api/scan/parlay` legs, `/api/bets/*`) can produce engine1 input
+ * without re-implementing the resolution chain.
+ *
+ * Never throws. Every step is independently fault-tolerant:
+ *   - player_id_map miss        → team/opponent unknown, features still partial
+ *   - no game tonight           → no gameId, gameId-dependent features omitted
+ *   - feature fetch fails       → features {} returned, engine1 lands C
+ *   - trap fetch fails          → trap defaults to no signals firing
+ *   - game logs unavailable     → consistency defaults to 'unknown'
+ *
+ * The caller (analyzeViaEngine1) reads the returned `errors` array and
+ * downgrades confidence accordingly via the adapter's reasoning string.
+ */
+
+const axios = require('axios');
+const { getSportConfig } = require('../../config/sports');
+const { getSupabaseServiceClient } = require('../../utils/supabase');
+const { normalizeName } = require('../../utils/normalize');
+const featureCache = require('./featureCache');
+const trapDetection = require('./trapDetection');
+const consistencyScore = require('./consistencyScore');
+const gameLogService = require('./gameLogService');
+
+const HTTP_TIMEOUT_MS = 8_000;
+
+// Resolve a free-form player + sport to a roster row. Returns null on
+// any failure so callers can still proceed with partial features.
+async function lookupPlayer({ player, sport }) {
+  if (!player || !sport) return null;
+  try {
+    const supabase = getSupabaseServiceClient();
+    const norm = normalizeName(player);
+    const { data, error } = await supabase
+      .from('player_id_map')
+      .select('display_name, normalized_name, espn_id, team_abbr, sport')
+      .eq('sport', sport)
+      .eq('normalized_name', norm)
+      .limit(1)
+      .maybeSingle();
+    if (error || !data) return null;
+    return data;
+  } catch (err) {
+    console.warn('[computeFeatures] player lookup failed:', err.message);
+    return null;
+  }
+}
+
+// Pull today's scoreboard for the sport and find the game the player's
+// team plays in. Returns { gameId, opponentAbbr, isHome } or null.
+async function lookupTodayGame({ sport, teamAbbr }) {
+  if (!sport || !teamAbbr) return null;
+  let sportCfg;
+  try { sportCfg = getSportConfig(sport); } catch { return null; }
+  try {
+    const res = await axios.get(sportCfg.espnScoreboard, { timeout: HTTP_TIMEOUT_MS });
+    const events = res.data?.events || [];
+    for (const ev of events) {
+      const comp = ev?.competitions?.[0];
+      if (!comp) continue;
+      const competitors = comp.competitors || [];
+      const home = competitors.find((c) => c.homeAway === 'home');
+      const away = competitors.find((c) => c.homeAway === 'away');
+      const homeAbbr = home?.team?.abbreviation;
+      const awayAbbr = away?.team?.abbreviation;
+      if (homeAbbr === teamAbbr) {
+        return { gameId: String(ev.id), opponentAbbr: awayAbbr, isHome: true };
+      }
+      if (awayAbbr === teamAbbr) {
+        return { gameId: String(ev.id), opponentAbbr: homeAbbr, isHome: false };
+      }
+    }
+    return null;
+  } catch (err) {
+    console.warn('[computeFeatures] scoreboard fetch failed:', err.message);
+    return null;
+  }
+}
+
+async function safeGetFeatures(input) {
+  try {
+    const payload = await featureCache.getFeatures(input);
+    return payload?.features || {};
+  } catch (err) {
+    console.warn('[computeFeatures] feature fetch failed:', err.message);
+    return {};
+  }
+}
+
+async function safeGetTrap(input) {
+  const fallback = { composite: 0, signals: {}, active_count: 0, recommendation: 'proceed' };
+  try {
+    return (await trapDetection.getTrapScore(input)) || fallback;
+  } catch (err) {
+    console.warn('[computeFeatures] trap detection failed:', err.message);
+    return fallback;
+  }
+}
+
+async function safeGetConsistency({ playerName, sport, statType }) {
+  const fallback = { consistency: 'unknown', score: null, games: 0 };
+  try {
+    const logs = await gameLogService.getGameLogs(playerName, sport, 20);
+    if (!logs || logs.length === 0) return { result: fallback, gameLogs: [] };
+    const result = await consistencyScore.getConsistency({
+      playerName, sport, statType, gameLogs: logs,
+    });
+    return { result: result || fallback, gameLogs: logs };
+  } catch (err) {
+    console.warn('[computeFeatures] consistency failed:', err.message);
+    return { result: fallback, gameLogs: [] };
+  }
+}
+
+async function computeFeaturesForProp(rawProp = {}) {
+  const errors = [];
+  const player = rawProp.player;
+  const statType = rawProp.stat_type || rawProp.statType;
+  const line = Number(rawProp.line);
+  const direction = rawProp.direction || 'over';
+  const book = rawProp.book || 'unknown';
+  // Default to NBA when caller omits — matches what legacy analyzeProp does.
+  const sport = (rawProp.sport || 'nba').toLowerCase();
+
+  if (!player || !statType || !Number.isFinite(line)) {
+    errors.push('missing required fields (player, stat_type, or line)');
+  }
+
+  const roster = await lookupPlayer({ player, sport });
+  if (!roster) errors.push('player_not_found_in_id_map');
+
+  const teamAbbr = roster?.team_abbr ?? null;
+  const playerId = roster?.espn_id ?? null;
+
+  const game = teamAbbr ? await lookupTodayGame({ sport, teamAbbr }) : null;
+  if (!game) errors.push('no_game_scheduled_today');
+
+  const gameContext = {
+    home_away: game ? (game.isHome ? 'home' : 'away') : null,
+  };
+
+  const features = await safeGetFeatures({
+    playerId,
+    playerName: player,
+    statType,
+    sport,
+    teamAbbr,
+    opponentAbbr: game?.opponentAbbr ?? null,
+    gameId: game?.gameId ?? null,
+    gameContext,
+  });
+
+  if (!features || Object.keys(features).length === 0) {
+    errors.push('no_features_computed');
+  }
+
+  const trap = await safeGetTrap({
+    playerName: player,
+    statType,
+    sport,
+    gameId: game?.gameId ?? null,
+    gameContext,
+    features,
+    odds: { playerLine: line, consensus: null },
+  });
+
+  const { result: consistency, gameLogs } = await safeGetConsistency({
+    playerName: player, sport, statType,
+  });
+
+  return {
+    // Shape engine1.gradeProp() consumes.
+    features,
+    trap,
+    consistency,
+    prop: { line, direction },
+    // Extra context the wiring helper (Fix 2) uses to build human-readable
+    // reasoning sentences. Not consumed by engine1 itself.
+    meta: {
+      player,
+      statType,
+      line,
+      direction,
+      book,
+      sport,
+      teamAbbr,
+      playerId,
+      opponentAbbr: game?.opponentAbbr ?? null,
+      gameId: game?.gameId ?? null,
+      isHome: game?.isHome ?? null,
+      gameLogs,
+      errors,
+    },
+  };
+}
+
+module.exports = {
+  computeFeaturesForProp,
+  __internals: {
+    lookupPlayer,
+    lookupTodayGame,
+    safeGetFeatures,
+    safeGetTrap,
+    safeGetConsistency,
+  },
+};

src/services/parlayScanService.js

@@ -1,4 +1,8 @@
-const { analyzeProp } = require('./propAnalyzer');
+// ARCH-1 Step 4 (Session 7f): /api/scan/parlay legs now grade via
+// engine1 (computeFeatures → engine1 → gradeAdapter) instead of the
+// legacy `analyzeProp`. Response shape is byte-compatible. Parallel
+// resolution from PERF-2 is preserved (still inside Promise.allSettled).
+const { analyzeViaEngine1 } = require('./intelligence/analyzeViaEngine1');
 const { getOdds } = require('./oddsService');
 const { detectCorrelations } = require('./correlationEngine');
 const { gradeParlayFromLegs } = require('./parlayGrader');
@@ -28,7 +32,7 @@ async function scanParlay(user, legs) {
   // than the old sequential loop. allSettled preserves leg order and
   // lets a single failed leg surface as an error stub instead of
   // crashing the whole parlay.
-  const settled = await Promise.allSettled(legs.map((leg) => analyzeProp(leg)));
+  const settled = await Promise.allSettled(legs.map((leg) => analyzeViaEngine1(leg)));
   const legResults = settled.map((s, i) => {
     if (s.status === 'fulfilled') return s.value;
     return {