import { getPiffPropsForGame, formatPiffForPrompt, loadPiffPropsForDate, PiffLeg } from './piff';
import { getDigimonForGame, formatDigimonForPrompt, loadDigimonPicksForDate, DigimonPick } from './digimon';
import { getKenPomMatchup, formatKenPomForPrompt } from './kenpom';
import { getCornerScoutForGame, formatCornerScoutForPrompt, isSoccerLeague, loadCornerScoutData, CornerScoutMatch } from './corner-scout';
import {
  getTeamBatting,
  getTeamPitching,
  getStarterProfile,
  getTeamBattingProjection,
  getTeamPitchingProjection,
  formatFangraphsForPrompt,
} from './fangraphs';
import { getBillJamesMatchup, formatBillJamesForPrompt, getParkFactor } from './bill-james';
import { getFourFactorsMatchup, formatFourFactorsForPrompt } from './four-factors';
import { getMlbProbableStarters } from './espn-mlb';
import { countMlbPropFeedRows, fetchMlbPropCandidates, MlbPropCandidate } from './mlb-prop-markets';
import { mlbPhaseSignal } from './rie/signals/mlb-phase-signal';
import {
  fetchTeamPropMarketCandidates,
  formatTeamPropMarketCandidatesForPrompt,
  TeamPropMarketCandidate,
  validateTeamPropsAgainstMarketCandidates,
} from './team-prop-market-candidates';
import {
  getPlayerPropFallbackDeltaForLeague,
  getPlayerPropLabelForLeague,
  getSupportedPlayerPropLabels,
  normalizePlayerPropMarketStat,
} from './player-prop-market-registry';
import { buildPlayerPropSignal } from './player-prop-signals';
import { formatTournamentContextForPrompt } from '../tournament/context-engine';
import { formatRosterForPrompt, isPlayerOnTeam, resolveCanonicalName } from './canonical-names';
import { getNarrativeSystemPromptAddendum, getTotalsEnrichmentPrompt, getDvpEnrichmentPrompt, classifySpreadScenario, classifyConfidenceTier, NarrativeContext } from './narrative-engine';
import { normalizePublicForecastNarrative, reconcilePublicForecastProjection } from './public-forecast-normalizer';
import type { TeamPlusDecision } from './team-plus';
import pool from '../db';
import { sanitizeLlmText } from '../lib/llm-text';
import { getCurrentEtDateKey, getEtDateKey } from '../lib/league-windows';
import { usesAssetBackedPropHighlights } from '../lib/prop-highlights';

// ── API Usage Tracking ──────────────────────────────────────
export interface LLMContext {
  category: string;
  subcategory?: string;
  eventId?: string;
  league?: string;
}

function trackUsage(params: {
  category: string;
  subcategory?: string;
  eventId?: string;
  league?: string;
  provider: string;
  model: string;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  responseTimeMs: number;
  success: boolean;
  errorMessage?: string;
  metadata?: Record<string, any>;
}) {
  pool.query(
    `INSERT INTO rm_api_usage (category, subcategory, event_id, league, provider, model, input_tokens, output_tokens, total_tokens, response_time_ms, success, error_message, metadata)
     VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)`,
    [params.category, params.subcategory || null, params.eventId || null, params.league || null,
     params.provider, params.model, params.inputTokens, params.outputTokens, params.totalTokens,
     params.responseTimeMs, params.success, params.errorMessage || null,
     JSON.stringify(params.metadata || {})]
  ).catch(err => console.error('[api-usage] Failed to track:', err.message));
}

// ── LLM Configuration ───────────────────────────────────────
// Primary: Codex via ChatGPT OAuth backend (if available)
// Secondary: Claude via Anthropic direct/API key config
// Fallback: Grok (x.ai)

import { readFileSync, writeFileSync } from 'fs';

const ANTHROPIC_API_URL = 'https://api.anthropic.com/v1/messages';
const ANTHROPIC_MODEL = process.env.CLAUDE_MODEL || 'claude-opus-4-6';
const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_CODE_OAUTH_TOKEN || '';
const ANTHROPIC_CLAUDE_CODE_BETA = 'claude-code-20250219,oauth-2025-04-20,fine-grained-tool-streaming-2025-05-14';
const ANTHROPIC_CLAUDE_CODE_UA = process.env.CLAUDE_CODE_USER_AGENT || 'claude-cli/1.0.67';

const CODEX_AUTH_JSON_PATH = process.env.CODEX_AUTH_JSON_PATH || '/home/administrator/.codex/auth.json';
const CODEX_API_URL = process.env.CODEX_API_URL || 'https://chatgpt.com/backend-api/codex/responses';
const CODEX_MODEL = process.env.CODEX_MODEL || 'gpt-5.4';
const CODEX_OAUTH_CLIENT_ID = 'app_EMoamEEZ73f0CkXaXp7hrann';
const CODEX_OAUTH_TOKEN_URL = 'https://auth.openai.com/oauth/token';
const CODEX_REFRESH_SKEW_MS = 2 * 60 * 1000;

const GROK_API_KEY = process.env.GROK_API_KEY || '';
const GROK_API_URL = process.env.GROK_API_URL || 'https://api.x.ai/v1/chat/completions';
const GROK_MODEL = process.env.GROK_MODEL || 'grok-4-1-fast-reasoning';

type CodexAuthFile = {
  auth_mode?: string;
  last_refresh?: string;
  tokens?: {
    access_token?: string;
    refresh_token?: string;
    account_id?: string;
    id_token?: string;
  };
};

function decodeJwtExpMs(token: string): number | null {
  const parts = token.split('.');
  if (parts.length < 2) return null;
  try {
    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')) as { exp?: number };
    return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
  } catch {
    return null;
  }
}

function loadCodexAuthFile(): CodexAuthFile | null {
  try {
    return JSON.parse(readFileSync(CODEX_AUTH_JSON_PATH, 'utf8')) as CodexAuthFile;
  } catch {
    return null;
  }
}

function saveCodexAuthFile(payload: CodexAuthFile): void {
  writeFileSync(CODEX_AUTH_JSON_PATH, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
}

async function refreshCodexAccessToken(authFile: CodexAuthFile): Promise<string> {
  const refreshToken = authFile.tokens?.refresh_token;
  if (!refreshToken) throw new Error('Codex auth is missing refresh_token');

  const res = await fetch(CODEX_OAUTH_TOKEN_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: CODEX_OAUTH_CLIENT_ID,
    }),
  });

  if (!res.ok) {
    const errText = await res.text();
    throw new Error(`Codex refresh failed ${res.status}: ${errText.slice(0, 200)}`);
  }

  const refreshPayload = await res.json() as { access_token?: string; refresh_token?: string };
  const accessToken = String(refreshPayload.access_token || '').trim();
  if (!accessToken) throw new Error('Codex refresh returned no access_token');

  const updated: CodexAuthFile = {
    ...authFile,
    last_refresh: new Date().toISOString(),
    tokens: {
      ...authFile.tokens,
      access_token: accessToken,
      refresh_token: String(refreshPayload.refresh_token || refreshToken).trim(),
    },
  };
  saveCodexAuthFile(updated);
  return accessToken;
}

async function resolveCodexAccessToken(forceRefresh = false): Promise<string | null> {
  const directToken = String(process.env.CODEX_OAUTH_TOKEN || '').trim();
  if (directToken) return directToken;

  const authFile = loadCodexAuthFile();
  const accessToken = String(authFile?.tokens?.access_token || '').trim();
  if (!authFile || !accessToken) return null;

  if (!forceRefresh) {
    const expMs = decodeJwtExpMs(accessToken);
    if (expMs && expMs > Date.now() + CODEX_REFRESH_SKEW_MS) {
      return accessToken;
    }
  }

  return refreshCodexAccessToken(authFile);
}

async function readCodexSseText(res: Response): Promise<{ text: string; usage: any }> {
  const reader = res.body?.getReader();
  if (!reader) throw new Error('Codex response body is not readable');

  const decoder = new TextDecoder();
  let buffer = '';
  let text = '';
  let usage: any = null;

  const flushEvent = (chunk: string) => {
    const lines = chunk
      .split('\n')
      .map((line) => line.replace(/\r$/, ''))
      .filter(Boolean);
    if (!lines.length) return;

    const dataLines = lines
      .filter((line) => line.startsWith('data:'))
      .map((line) => line.slice(5).trim());
    if (!dataLines.length) return;

    const joined = dataLines.join('\n');
    if (!joined || joined === '[DONE]') return;

    const payload = JSON.parse(joined) as any;
    if (payload.type === 'response.output_text.delta' && typeof payload.delta === 'string') {
      text += payload.delta;
    } else if (payload.type === 'response.completed') {
      usage = payload.response?.usage || usage;
    } else if (payload.type === 'response.failed') {
      const err = payload.response?.error?.message || payload.response?.error || 'Codex response failed';
      throw new Error(String(err));
    }
  };

  while (true) {
    const { done, value } = await reader.read();
    buffer += decoder.decode(value || new Uint8Array(), { stream: !done });

    let boundary = buffer.indexOf('\n\n');
    while (boundary !== -1) {
      const eventChunk = buffer.slice(0, boundary);
      buffer = buffer.slice(boundary + 2);
      flushEvent(eventChunk);
      boundary = buffer.indexOf('\n\n');
    }

    if (done) break;
  }

  if (buffer.trim()) flushEvent(buffer);

  return { text: text.trim(), usage };
}

async function callCodexDirect(
  systemPrompt: string,
  userPrompt: string,
  maxTokens: number,
  temperature: number,
  timeoutMs: number,
  context?: LLMContext,
): Promise<string> {
  let accessToken = await resolveCodexAccessToken();
  if (!accessToken) throw new Error('No Codex OAuth token configured');

  const cleanSystemPrompt = sanitizeLlmText(systemPrompt).trim();
  const cleanUserPrompt = sanitizeLlmText(userPrompt);
  const promptWasSanitized = cleanSystemPrompt !== systemPrompt || cleanUserPrompt !== userPrompt;
  const startMs = Date.now();

  const run = async (token: string) => {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), timeoutMs);
    try {
      const res = await fetch(CODEX_API_URL, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${token}`,
          'Content-Type': 'application/json',
          Accept: 'text/event-stream',
        },
        body: JSON.stringify({
          model: CODEX_MODEL,
          instructions: cleanSystemPrompt || 'You are a helpful assistant.',
          input: [
            {
              role: 'user',
              content: [{ type: 'input_text', text: cleanUserPrompt }],
            },
          ],
          store: false,
          stream: true,
        }),
        signal: controller.signal,
      });
      clearTimeout(timeout);
      return res;
    } catch (err) {
      clearTimeout(timeout);
      throw err;
    }
  };

  let res = await run(accessToken);
  if (res.status === 401) {
    accessToken = await resolveCodexAccessToken(true);
    if (!accessToken) throw new Error('Codex OAuth refresh failed');
    res = await run(accessToken);
  }

  const responseTimeMs = Date.now() - startMs;
  if (!res.ok) {
    const errText = await res.text();
    const requestId = res.headers.get('x-request-id') || res.headers.get('request-id') || 'unknown';
    console.error(
      `[llm] Codex API error ${res.status} (req ${requestId}, system_chars=${cleanSystemPrompt.length}, user_chars=${cleanUserPrompt.length}, sanitized=${promptWasSanitized}):`,
      errText.slice(0, 500),
    );
    if (context) {
      trackUsage({
        ...context,
        provider: 'codex-oauth',
        model: CODEX_MODEL,
        inputTokens: 0,
        outputTokens: 0,
        totalTokens: 0,
        responseTimeMs,
        success: false,
        errorMessage: `Codex ${res.status} req ${requestId}: ${errText.slice(0, 160)}`,
        metadata: {
          requestId,
          systemChars: cleanSystemPrompt.length,
          userChars: cleanUserPrompt.length,
          promptWasSanitized,
        },
      });
    }
    throw new Error(`Codex ${res.status} req ${requestId}`);
  }

  const { text, usage } = await readCodexSseText(res);
  if (!text) throw new Error('Codex returned empty content');
  console.log(`[llm] Codex responded (${text.length} chars)`);

  if (context) {
    trackUsage({
      ...context,
      provider: 'codex-oauth',
      model: CODEX_MODEL,
      inputTokens: usage?.input_tokens || 0,
      outputTokens: usage?.output_tokens || 0,
      totalTokens: usage?.total_tokens || (usage?.input_tokens || 0) + (usage?.output_tokens || 0),
      responseTimeMs,
      success: true,
      metadata: {
        systemChars: cleanSystemPrompt.length,
        userChars: cleanUserPrompt.length,
        promptWasSanitized,
      },
    });
  }

  return text.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
}

/** Call Claude via Anthropic OAuth token (sk-ant-oat01-*) or API key */
async function callAnthropicDirect(
  systemPrompt: string,
  userPrompt: string,
  maxTokens: number,
  temperature: number,
  timeoutMs: number,
  context?: LLMContext
): Promise<string> {
  if (!ANTHROPIC_API_KEY) throw new Error('No ANTHROPIC_API_KEY configured');

  const cleanSystemPrompt = sanitizeLlmText(systemPrompt);
  const cleanUserPrompt = sanitizeLlmText(userPrompt);
  const promptWasSanitized = cleanSystemPrompt !== systemPrompt || cleanUserPrompt !== userPrompt;

  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);
  const startMs = Date.now();

  // Detect OAuth token vs direct API key by prefix
  const isOAuth = !ANTHROPIC_API_KEY.startsWith('sk-ant-api');
  const authHeaders: Record<string, string> = isOAuth
    ? {
        'Authorization': `Bearer ${ANTHROPIC_API_KEY}`,
        'anthropic-beta': ANTHROPIC_CLAUDE_CODE_BETA,
        'anthropic-dangerous-direct-browser-access': 'true',
        'user-agent': ANTHROPIC_CLAUDE_CODE_UA,
        'x-app': 'cli',
        'accept': 'application/json',
      }
    : { 'x-api-key': ANTHROPIC_API_KEY };
  const systemPayload = isOAuth
    ? [
        { type: 'text', text: "You are Claude Code, Anthropic's official CLI for Claude." },
        ...(cleanSystemPrompt ? [{ type: 'text', text: cleanSystemPrompt }] : []),
      ]
    : cleanSystemPrompt;

  try {
    const res = await fetch(ANTHROPIC_API_URL, {
      method: 'POST',
      headers: {
        ...authHeaders,
        'Content-Type': 'application/json',
        'anthropic-version': '2023-06-01',
      },
      body: JSON.stringify({
        model: ANTHROPIC_MODEL,
        system: systemPayload,
        messages: [{ role: 'user', content: cleanUserPrompt }],
        temperature,
        max_tokens: maxTokens,
      }),
      signal: controller.signal,
    });

    clearTimeout(timeout);
    const responseTimeMs = Date.now() - startMs;

    if (!res.ok) {
      const errText = await res.text();
      const requestId = res.headers.get('request-id') || 'unknown';
      console.error(
        `[llm] Claude API error ${res.status} (req ${requestId}, system_chars=${cleanSystemPrompt.length}, user_chars=${cleanUserPrompt.length}, sanitized=${promptWasSanitized}):`,
        errText.slice(0, 500),
      );
      if (context) {
        trackUsage({
          ...context, provider: 'claude-direct', model: ANTHROPIC_MODEL,
          inputTokens: 0, outputTokens: 0, totalTokens: 0, responseTimeMs,
          success: false, errorMessage: `Claude Opus ${res.status} req ${requestId}: ${errText.slice(0, 160)}`,
          metadata: {
            requestId,
            systemChars: cleanSystemPrompt.length,
            userChars: cleanUserPrompt.length,
            promptWasSanitized,
          },
        });
      }
      throw new Error(`Claude Opus ${res.status} req ${requestId}`);
    }

    const data = await res.json() as any;
    // Anthropic Messages API returns content[0].text
    let content = data.content?.[0]?.text || '';
    content = content.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
    if (!content) throw new Error('Claude Opus returned empty content');
    console.log(`[llm] Claude Opus responded (${content.length} chars)`);

    if (context) {
      const usage = data.usage || {};
      trackUsage({
        ...context, provider: 'claude-direct', model: ANTHROPIC_MODEL,
        inputTokens: usage.input_tokens || 0,
        outputTokens: usage.output_tokens || 0,
        totalTokens: (usage.input_tokens || 0) + (usage.output_tokens || 0),
        responseTimeMs, success: true,
        metadata: {
          systemChars: cleanSystemPrompt.length,
          userChars: cleanUserPrompt.length,
          promptWasSanitized,
        },
      });
    }

    return content;
  } catch (err) {
    clearTimeout(timeout);
    if (context && !(err as Error).message?.includes('Claude Opus')) {
      trackUsage({
        ...context, provider: 'claude-direct', model: ANTHROPIC_MODEL,
        inputTokens: 0, outputTokens: 0, totalTokens: 0, responseTimeMs: Date.now() - startMs,
        success: false, errorMessage: (err as Error).message,
      });
    }
    throw err;
  }
}

/** Unified LLM call — tries Codex first, then Claude, then Grok fallback */
export async function callLLM(
  systemPrompt: string,
  userPrompt: string,
  opts: { maxTokens?: number; temperature?: number; timeoutMs?: number } = {},
  context?: LLMContext
): Promise<string> {
  const { maxTokens = 4000, temperature = 0.6, timeoutMs = 90000 } = opts;

  // 1. Try Codex via ChatGPT OAuth backend
  try {
    return await callCodexDirect(systemPrompt, userPrompt, maxTokens, temperature, timeoutMs, context);
  } catch (err) {
    console.warn('[llm] Codex failed, falling back to Claude:', (err as Error).message);
  }

  // 2. Try Claude via Anthropic
  try {
    return await callAnthropicDirect(systemPrompt, userPrompt, maxTokens, temperature, timeoutMs, context);
  } catch (err) {
    console.warn('[llm] Claude failed, falling back to Grok:', (err as Error).message);
  }

  // 3. Fallback: Grok
  const content = await callProvider({
    apiUrl: GROK_API_URL,
    apiKey: GROK_API_KEY,
    model: GROK_MODEL,
    systemPrompt,
    userPrompt,
    maxTokens,
    temperature,
    timeoutMs,
    label: 'Grok',
  }, context);
  if (content) return content;

  throw new Error('All LLM providers failed');
}

async function callProvider(cfg: {
  apiUrl: string;
  apiKey: string;
  model: string;
  systemPrompt: string;
  userPrompt: string;
  maxTokens: number;
  temperature: number;
  timeoutMs: number;
  headers?: Record<string, string>;
  label: string;
}, context?: LLMContext): Promise<string> {
  const cleanSystemPrompt = sanitizeLlmText(cfg.systemPrompt);
  const cleanUserPrompt = sanitizeLlmText(cfg.userPrompt);
  const promptWasSanitized = cleanSystemPrompt !== cfg.systemPrompt || cleanUserPrompt !== cfg.userPrompt;
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), cfg.timeoutMs);
  const startMs = Date.now();

  try {
    const res = await fetch(cfg.apiUrl, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${cfg.apiKey}`,
        'Content-Type': 'application/json',
        ...(cfg.headers || {}),
      },
      body: JSON.stringify({
        model: cfg.model,
        messages: [
          { role: 'system', content: cleanSystemPrompt },
          { role: 'user', content: cleanUserPrompt },
        ],
        temperature: cfg.temperature,
        max_tokens: cfg.maxTokens,
      }),
      signal: controller.signal,
    });

    clearTimeout(timeout);
    const responseTimeMs = Date.now() - startMs;

    if (!res.ok) {
      const errText = await res.text();
      const requestId = res.headers.get('request-id') || 'unknown';
      console.error(
        `[llm] ${cfg.label} API error ${res.status} (req ${requestId}, system_chars=${cleanSystemPrompt.length}, user_chars=${cleanUserPrompt.length}, sanitized=${promptWasSanitized}):`,
        errText.slice(0, 500),
      );
      if (context) {
        trackUsage({
          ...context, provider: cfg.label.toLowerCase(), model: cfg.model,
          inputTokens: 0, outputTokens: 0, totalTokens: 0, responseTimeMs,
          success: false, errorMessage: `${cfg.label} ${res.status} req ${requestId}: ${errText.slice(0, 160)}`,
          metadata: {
            requestId,
            systemChars: cleanSystemPrompt.length,
            userChars: cleanUserPrompt.length,
            promptWasSanitized,
          },
        });
      }
      throw new Error(`${cfg.label} ${res.status} req ${requestId}`);
    }

    const data = await res.json() as any;
    let content = data.choices?.[0]?.message?.content || '';
    // Strip markdown code fences
    content = content.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
    // Fix Grok's invalid JSON: +165 → 165 (JSON doesn't allow + prefix on numbers)
    content = content.replace(/:\s*\+(\d)/g, ': $1');
    if (!content) throw new Error(`${cfg.label} returned empty content`);
    console.log(`[llm] ${cfg.label} responded (${content.length} chars)`);

    // Track usage (fire and forget)
    if (context) {
      const usage = data.usage || {};
      trackUsage({
        ...context,
        provider: cfg.label.toLowerCase(),
        model: cfg.model,
        inputTokens: usage.prompt_tokens || 0,
        outputTokens: usage.completion_tokens || 0,
        totalTokens: usage.total_tokens || (usage.prompt_tokens || 0) + (usage.completion_tokens || 0),
        responseTimeMs,
        success: true,
        metadata: {
          systemChars: cleanSystemPrompt.length,
          userChars: cleanUserPrompt.length,
          promptWasSanitized,
        },
      });
    }

    return content;
  } catch (err) {
    clearTimeout(timeout);
    if (context && !(err as Error).message?.includes(cfg.label)) {
      trackUsage({
        ...context, provider: cfg.label.toLowerCase(), model: cfg.model,
        inputTokens: 0, outputTokens: 0, totalTokens: 0, responseTimeMs: Date.now() - startMs,
        success: false, errorMessage: (err as Error).message,
      });
    }
    throw err;
  }
}

// Cache PIFF map per ET date to avoid re-reading files for every forecast
const piffMapCache = new Map<string, Record<string, PiffLeg[]>>();
function getPiffMap(startsAt?: string): Record<string, PiffLeg[]> {
  const targetDate = getEtDateKey(startsAt || '') || getCurrentEtDateKey();
  if (!piffMapCache.has(targetDate)) {
    piffMapCache.set(targetDate, loadPiffPropsForDate(targetDate));
  }
  return piffMapCache.get(targetDate)!;
}

// Cache DIGIMON map per ET date
const digimonMapCache = new Map<string, Record<string, DigimonPick[]>>();
function getDigimonMap(startsAt?: string): Record<string, DigimonPick[]> {
  const targetDate = getEtDateKey(startsAt || '') || getCurrentEtDateKey();
  if (!digimonMapCache.has(targetDate)) {
    digimonMapCache.set(targetDate, loadDigimonPicksForDate(targetDate));
  }
  return digimonMapCache.get(targetDate)!;
}

export interface ForecastResult {
  summary: string;
  winner_pick: string;
  confidence: number;
  spread_analysis: string;
  total_analysis: string;
  key_factors: string[];
  sharp_money_indicator: string;
  line_movement_analysis: string;
  prop_highlights: Array<{ player: string; prop: string; recommendation: string; reasoning: string }>;
  weather_impact?: string;
  injury_notes?: string;
  historical_trend: string;
  value_rating: number; // 1-10
  // Market pricing generated by Grok when live feed data isn't available
  projected_lines?: {
    moneyline: { home: number; away: number };
    spread: { home: number; away: number };
    total: number;
  };
  // ── Golden Rule projection fields ──
  projected_margin: number;           // signed: positive = home favored, negative = away favored
  projected_total_points: number;     // combined score projection
  projected_team_score_home?: number; // optional individual team score
  projected_team_score_away?: number; // optional individual team score
  // ── BENCHMARK RULE: Market-relative value fields (computed server-side post-LLM) ──
  forecast_side: string;              // team with VALUE against the market spread (may differ from winner_pick)
  spread_edge: number;                // signed edge in points from forecast_side perspective (always positive for the value side)
  total_direction: 'OVER' | 'UNDER' | 'NONE'; // model total vs market total
  total_edge: number;                 // model total minus market total (positive = over, negative = under)
  projected_winner: string;           // who the model projects to win outright (same as winner_pick, for clarity)
  // ── Clip metadata (generated post-LLM) ──
  clip_metadata?: Array<{
    entity_id: string;
    clip_type: string;
    display_text: string;
    clip_data?: {
      forecasted_value?: number | null;
      market_value?: number | null;
      direction?: 'OVER' | 'UNDER' | 'NONE';
      edge_pct?: number | null;
      confidence_pct?: number | null;
      winner?: string | null;
      forecast_side?: string | null;
      display_context?: string;
    };
  }>;
  mlb_phase_context?: {
    phase_label?: string | null;
    k_rank?: number | null;
    lineup_certainty?: string | null;
    park_factor?: number | null;
    weather_impact?: string | null;
  };
  team_plus_decision?: {
    winner_pick: string;
    home_score: number;
    away_score: number;
    confidence: number;
    locked_margin: number;
    explanation: string[];
  };
}

function clampConfidenceValue(value: number, min: number, max: number): number {
  return Math.max(min, Math.min(max, value));
}

function toFiniteConfidenceNumber(value: unknown): number | null {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : null;
}

function normalizeRawConfidence(value: unknown): number | null {
  const parsed = toFiniteConfidenceNumber(value);
  if (parsed == null) return null;
  if (parsed > 1 && parsed <= 100) return clampConfidenceValue(parsed / 100, 0, 1);
  if (parsed < 0 || parsed > 1) return null;
  return parsed;
}

export function deriveCalibratedForecastConfidence(params: {
  spreadEdge?: number | null;
  totalEdge?: number | null;
  valueRating?: number | null;
  rawConfidence?: number | null;
  marketBacked?: boolean;
}): number {
  const spreadEdge = Math.min(Math.abs(toFiniteConfidenceNumber(params.spreadEdge) ?? 0), 5);
  const totalEdge = Math.min(Math.abs(toFiniteConfidenceNumber(params.totalEdge) ?? 0), 6);
  const valueRating = clampConfidenceValue(toFiniteConfidenceNumber(params.valueRating) ?? 5, 1, 10);
  const rawConfidence = normalizeRawConfidence(params.rawConfidence);
  const marketBacked = params.marketBacked !== false;

  if (!marketBacked) {
    const baseline = rawConfidence ?? 0.5;
    const calibratedNoMarket = 0.5
      + (baseline - 0.5)
      + (valueRating - 5) * 0.015;
    return Math.round(clampConfidenceValue(calibratedNoMarket, 0.38, 0.88) * 1000) / 1000;
  }

  let calibrated = 0.5
    + spreadEdge * 0.04
    + totalEdge * 0.022
    + (valueRating - 5) * 0.012;

  // Raw LLM confidence is still secondary, but it needs enough influence to
  // break ties between similarly priced edges instead of collapsing everything
  // into the same 0.57-0.60 bucket.
  if (rawConfidence != null) {
    calibrated += (rawConfidence - 0.5) * 0.18;
  }

  const edgeSeparationBoost = clampConfidenceValue(
    (spreadEdge / 5) * 0.04 + (totalEdge / 6) * 0.025,
    0,
    0.065,
  );
  calibrated = 0.5 + (calibrated - 0.5) * (1.08 + edgeSeparationBoost);

  return Math.round(clampConfidenceValue(calibrated, 0.35, 0.88) * 1000) / 1000;
}

function getTotalSignalDeadband(league: string | null | undefined): number {
  switch ((league || '').toLowerCase()) {
    case 'mlb':
      // Half-run deltas still matter in MLB. Keep the deadband smaller so
      // weak and moderate totals do not all collapse into the same bucket.
      return 0.5;
    default:
      return 0;
  }
}

function getSpreadSignalDeadband(league: string | null | undefined): number {
  switch ((league || '').toLowerCase()) {
    case 'mlb':
      // Preserve separation between thin and moderate run-line leans instead of
      // zeroing everything below three quarters of a run.
      return 0.5;
    default:
      return 0;
  }
}

function getProjectedMarginDeadband(league: string | null | undefined): number {
  switch ((league || '').toLowerCase()) {
    case 'mlb':
      // Keep coin-flip MLB winner leans from auto-flipping the run line, but do
      // not wipe out every sub-0.75 projection either.
      return 0.5;
    default:
      return 0;
  }
}

export function deriveSpreadSignal(params: {
  league: string | null | undefined;
  projectedMargin: number | null | undefined;
  marketHomeSpread: number | null | undefined;
  homeTeam: string;
  awayTeam: string;
  winnerPick: string;
}): { forecastSide: string; spreadEdge: number; spreadValue: number | null } {
  const projectedMargin = params.projectedMargin;
  const marketHomeSpread = params.marketHomeSpread;
  if (projectedMargin == null || marketHomeSpread == null) {
    return {
      forecastSide: params.winnerPick,
      spreadEdge: 0,
      spreadValue: null,
    };
  }

  const projectedMarginDeadband = getProjectedMarginDeadband(params.league);
  if (Math.abs(projectedMargin) < projectedMarginDeadband) {
    return {
      forecastSide: params.winnerPick,
      spreadEdge: 0,
      spreadValue: Math.round((marketHomeSpread + projectedMargin) * 10) / 10,
    };
  }

  const spreadValue = Math.round((marketHomeSpread + projectedMargin) * 10) / 10;
  const deadband = getSpreadSignalDeadband(params.league);
  if (Math.abs(spreadValue) < deadband) {
    return {
      forecastSide: params.winnerPick,
      spreadEdge: 0,
      spreadValue,
    };
  }

  if (spreadValue > 0) {
    return {
      forecastSide: params.homeTeam,
      spreadEdge: spreadValue,
      spreadValue,
    };
  }

  if (spreadValue < 0) {
    return {
      forecastSide: params.awayTeam,
      spreadEdge: Math.abs(spreadValue),
      spreadValue,
    };
  }

  return {
    forecastSide: params.winnerPick,
    spreadEdge: 0,
    spreadValue,
  };
}

export function deriveTotalSignal(params: {
  league: string | null | undefined;
  projectedTotal: number | null | undefined;
  marketTotal: number | null | undefined;
}): { direction: 'OVER' | 'UNDER' | 'NONE'; edge: number } {
  const projectedTotal = params.projectedTotal;
  const marketTotal = params.marketTotal;
  if (projectedTotal == null || marketTotal == null) {
    return { direction: 'NONE', edge: 0 };
  }

  const totalDiff = Math.round((projectedTotal - marketTotal) * 10) / 10;
  const deadband = getTotalSignalDeadband(params.league);
  if (Math.abs(totalDiff) < deadband) {
    return { direction: 'NONE', edge: 0 };
  }

  if (totalDiff > 0) {
    return { direction: 'OVER', edge: totalDiff };
  }
  if (totalDiff < 0) {
    return { direction: 'UNDER', edge: totalDiff };
  }
  return { direction: 'NONE', edge: 0 };
}

const NO_SIGNAL_PATTERNS = [
  /^no (line move|sharp|clear sharp|sharp money|line movement|significant line|notable movement)/i,
  /^(insufficient|without historical|with no tracked|no sharp move|no sharp money|no line move)/i,
  /^markets? (?:holding|hold|held|remain|remained|stayed) steady/i,
  /^markets? stable/i,
  /^lines? (?:have )?(?:remained|stayed) stable/i,
  /\bno notable (?:shift|movement|move)\b/i,
  /\bstable pricing\b/i,
  /\bconsensus on\b/i,
  /\bno clear sharp positioning\b/i,
  /\bno sharp moves detected\b/i,
  /\bno sharp market interest detected\b/i,
];

function looksLikeNoSignalNarrative(text: any): boolean {
  if (!text || typeof text !== 'string') return true;
  const trimmed = text.trim();
  if (!trimmed) return true;
  return NO_SIGNAL_PATTERNS.some((pattern) => pattern.test(trimmed));
}

function toFiniteNumber(value: any): number | null {
  if (value === null || value === undefined || value === '') return null;
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : null;
}

function formatMarketValue(value: number | null): string {
  if (value == null) return 'unknown';
  return Number.isInteger(value) ? String(value) : value.toFixed(1);
}

function formatPointDelta(value: number | null): string {
  if (value == null) return 'unknown';
  const abs = Math.abs(value);
  const formatted = Number.isInteger(abs) ? String(abs) : abs.toFixed(1);
  return `${formatted}-point`;
}

function buildSharpSignalSummary(dbAnalytics: any): string | null {
  const sharpMove = (dbAnalytics?.sharpMoves || []).find((row: any) => {
    return toFiniteNumber(row?.lineFrom) !== null
      || toFiniteNumber(row?.lineTo) !== null
      || toFiniteNumber(row?.lineChange) !== null;
  });
  if (!sharpMove) return null;

  const market = String(sharpMove.market || 'market').toLowerCase();
  const lineFrom = toFiniteNumber(sharpMove.lineFrom);
  const lineTo = toFiniteNumber(sharpMove.lineTo);
  const lineChange = toFiniteNumber(sharpMove.lineChange);
  const bookmaker = sharpMove.bookmaker ? ` at ${sharpMove.bookmaker}` : '';
  const steamTag = sharpMove.isSteamMove ? ' with steam confirmation' : '';
  const reverseTag = sharpMove.isReverseLine ? ' and reverse-line pressure' : '';

  return `Sharp move detected on ${market}: current markets moved from ${formatMarketValue(lineFrom)} to ${formatMarketValue(lineTo)} (${formatPointDelta(lineChange)})${bookmaker}${steamTag}${reverseTag}.`;
}

function buildSteamSignalSummary(dbAnalytics: any): string | null {
  const lineMovement = (dbAnalytics?.lineMovements || []).find((row: any) => {
    return row?.steamMove
      || toFiniteNumber(row?.openLine) !== null
      || toFiniteNumber(row?.currentLine) !== null
      || toFiniteNumber(row?.lineMovement) !== null;
  });

  if (lineMovement) {
    const market = String(lineMovement.marketType || 'market').toLowerCase();
    const openLine = toFiniteNumber(lineMovement.openLine);
    const currentLine = toFiniteNumber(lineMovement.currentLine);
    const lineMovementValue = toFiniteNumber(lineMovement.lineMovement);
    const direction = lineMovement.movementDirection ? ` ${String(lineMovement.movementDirection).toLowerCase()}` : '';
    const sharpAction = lineMovement.sharpAction ? ` Sharp action: ${String(lineMovement.sharpAction).toLowerCase()}.` : '';
    const reverseTag = lineMovement.reverseLineMove ? ' Reverse-line movement is active.' : '';

    return `Steam move detected on ${market}: current markets moved from ${formatMarketValue(openLine)} to ${formatMarketValue(currentLine)} (${formatPointDelta(lineMovementValue)})${direction}.${sharpAction}${reverseTag}`.trim();
  }

  const steamSharpMove = (dbAnalytics?.sharpMoves || []).find((row: any) => row?.isSteamMove);
  if (!steamSharpMove) return null;

  const market = String(steamSharpMove.market || 'market').toLowerCase();
  const lineFrom = toFiniteNumber(steamSharpMove.lineFrom);
  const lineTo = toFiniteNumber(steamSharpMove.lineTo);
  const lineChange = toFiniteNumber(steamSharpMove.lineChange);
  const bookmaker = steamSharpMove.bookmaker ? ` at ${steamSharpMove.bookmaker}` : '';

  return `Steam move detected on ${market}: current markets moved from ${formatMarketValue(lineFrom)} to ${formatMarketValue(lineTo)} (${formatPointDelta(lineChange)})${bookmaker}.`;
}

function enrichStructuredSignalNarratives<T extends { sharp_money_indicator?: string; line_movement_analysis?: string }>(forecast: T, dbAnalytics: any): T {
  const enriched = { ...forecast };
  const sharpSummary = buildSharpSignalSummary(dbAnalytics);
  const steamSummary = buildSteamSignalSummary(dbAnalytics);

  if (sharpSummary && looksLikeNoSignalNarrative(enriched.sharp_money_indicator)) {
    enriched.sharp_money_indicator = sharpSummary;
  }
  if (steamSummary && looksLikeNoSignalNarrative(enriched.line_movement_analysis)) {
    enriched.line_movement_analysis = steamSummary;
  }

  return enriched;
}

function syncForecastProjectionState<T extends ForecastResult>(
  forecast: T,
  context: {
    homeTeam: string;
    awayTeam: string;
    homeShort?: string;
    awayShort?: string;
    league?: string | null;
    spread?: any;
  },
  options?: { rebuildNarrative?: boolean },
): T {
  const projectionContext = {
    homeTeam: context.homeTeam,
    awayTeam: context.awayTeam,
    homeShort: context.homeShort,
    awayShort: context.awayShort,
    league: context.league,
    odds: { spread: context.spread },
  };

  const reconciled = reconcilePublicForecastProjection(forecast, projectionContext);
  if (!options?.rebuildNarrative) {
    return reconciled as T;
  }

  return normalizePublicForecastNarrative(reconciled, projectionContext) as T;
}

export async function generateForecast(context: {
  homeTeam: string;
  awayTeam: string;
  homeShort?: string;
  awayShort?: string;
  league: string;
  startsAt: string;
  moneyline: { home: number | null; away: number | null };
  spread: any;
  total: any;
  dbAnalytics: any;
  eventId?: string;
  tournamentContext?: any;
  lockedTeamDecision?: TeamPlusDecision | null;
}): Promise<ForecastResult> {
  // Fetch KenPom matchup data for NCAAB games
  let kenpomMatchup = null;
  if (context.league?.toLowerCase() === 'ncaab') {
    try {
      const gameDate = context.startsAt ? context.startsAt.slice(0, 10) : new Date().toISOString().slice(0, 10);
      kenpomMatchup = await getKenPomMatchup(context.homeTeam, context.awayTeam, 'ncaab', gameDate);
      if (kenpomMatchup) {
        console.log(`[kenpom] Loaded matchup data: ${kenpomMatchup.home?.teamName || 'unknown'} vs ${kenpomMatchup.away?.teamName || 'unknown'}`);
      }
    } catch (err: any) {
      console.warn(`[kenpom] Failed to load matchup: ${err.message}`);
    }
  }

  // Load Corner Scout data for soccer leagues
  let cornerScoutMatch: CornerScoutMatch | null = null;
  if (isSoccerLeague(context.league || '')) {
    try {
      const eventDateKey = getEtDateKey(context.startsAt || '') || getCurrentEtDateKey();
      cornerScoutMatch = getCornerScoutForGame(context.homeTeam, context.awayTeam, undefined, eventDateKey);
      if (cornerScoutMatch) {
        console.log(`[corner-scout] Loaded corner analysis: proj ${cornerScoutMatch.projection?.toFixed(1)} | line ${cornerScoutMatch.main_line} | edge ${cornerScoutMatch.edge?.toFixed(1)} | ${cornerScoutMatch.rating}`);
      }
    } catch (err: any) {
      console.warn(`[corner-scout] Failed to load: ${err.message}`);
    }
  }

  // Load FanGraphs sabermetric data + Bill James model for MLB
  let fangraphsSection = '';
  let billJamesSection = '';
  if (context.league?.toLowerCase() === 'mlb') {
    const now = new Date();
    const fgSeason = (now.getMonth() < 3 || (now.getMonth() === 2 && now.getDate() < 25))
      ? now.getFullYear() - 1 : now.getFullYear();
    const homeShort = context.homeShort?.toUpperCase() || '';
    const awayShort = context.awayShort?.toUpperCase() || '';

    if (homeShort && awayShort) {
      let homeStarterName: string | null = null;
      let awayStarterName: string | null = null;

      try {
        const probables = await getMlbProbableStarters({
          homeShort,
          awayShort,
          startsAt: context.startsAt || new Date().toISOString(),
        });
        homeStarterName = probables?.homeStarter?.name || null;
        awayStarterName = probables?.awayStarter?.name || null;
      } catch (err: any) {
        console.warn(`[espn-mlb] Failed to load probables: ${err.message}`);
      }

      // FanGraphs raw stats
      try {
        const [homeBat, awayBat, homePit, awayPit, homeBatProj, awayBatProj, homePitProj, awayPitProj, homeStarter, awayStarter] = await Promise.all([
          getTeamBatting(homeShort, fgSeason, 'full'),
          getTeamBatting(awayShort, fgSeason, 'full'),
          getTeamPitching(homeShort, fgSeason, 'full'),
          getTeamPitching(awayShort, fgSeason, 'full'),
          getTeamBattingProjection(homeShort, now.getFullYear()),
          getTeamBattingProjection(awayShort, now.getFullYear()),
          getTeamPitchingProjection(homeShort, now.getFullYear()),
          getTeamPitchingProjection(awayShort, now.getFullYear()),
          homeStarterName ? getStarterProfile(homeStarterName, homeShort, fgSeason) : Promise.resolve(null),
          awayStarterName ? getStarterProfile(awayStarterName, awayShort, fgSeason) : Promise.resolve(null),
        ]);
        fangraphsSection = formatFangraphsForPrompt({
          homeBat, awayBat, homePit, awayPit,
          homeStarter, awayStarter,
          homeStarterName, awayStarterName,
          homeBatProj, awayBatProj, homePitProj, awayPitProj,
          homeTeam: context.homeTeam, awayTeam: context.awayTeam,
        });
        if (fangraphsSection) {
          console.log(`[fangraphs] Loaded MLB analytics: home wRC+ ${homeBat?.wrcPlus?.toFixed(1) || 'N/A'}, away wRC+ ${awayBat?.wrcPlus?.toFixed(1) || 'N/A'}, home SP ${homeStarterName || 'N/A'}, away SP ${awayStarterName || 'N/A'}`);
        }
      } catch (err: any) {
        console.warn(`[fangraphs] Failed to load: ${err.message}`);
      }

      // Bill James sabermetric model (park factors, Pythagorean W%, Log5, RC, SecA, Component ERA)
      try {
        const bjData = await getBillJamesMatchup(homeShort, awayShort, fgSeason, homeStarterName || undefined, awayStarterName || undefined);
        billJamesSection = formatBillJamesForPrompt(bjData, context.homeTeam, context.awayTeam);
        if (billJamesSection) {
          const log5Pct = bjData.log5?.homeWinProbHFA;
          const parkRuns = bjData.park?.runs;
          console.log(`[bill-james] Loaded: park=${parkRuns?.toFixed(2) || 'N/A'} log5=${log5Pct ? (log5Pct * 100).toFixed(1) + '%' : 'N/A'} home RC/g=${bjData.homeRC?.rcPerGame?.toFixed(1) || 'N/A'} away RC/g=${bjData.awayRC?.rcPerGame?.toFixed(1) || 'N/A'}`);
        }
      } catch (err: any) {
        console.warn(`[bill-james] Failed to load: ${err.message}`);
      }
    }
  }

  // Load Four Factors + Pace model for NBA
  let fourFactorsSection = '';
  if (context.league?.toLowerCase() === 'nba') {
    const homeShort = context.homeShort?.toUpperCase() || '';
    const awayShort = context.awayShort?.toUpperCase() || '';
    if (homeShort && awayShort) {
      try {
        const ffData = await getFourFactorsMatchup(homeShort, awayShort);
        if (ffData) {
          fourFactorsSection = formatFourFactorsForPrompt(ffData);
          console.log(`[four-factors] Loaded: pace=${ffData.expectedPace.toFixed(0)} total=${ffData.expectedTotal.toFixed(0)} eFG_edge=${(ffData.efgEdge * 100).toFixed(1)}pp adjustments=${ffData.propAdjustments.length}`);
        }
      } catch (err: any) {
        console.warn(`[four-factors] Failed to load: ${err.message}`);
      }
    }
  }

  // Use tournament context if passed from forecast-builder (avoids double computation)
  const tournamentContext = context.tournamentContext || null;

  const prompt = buildPrompt({
    ...context,
    kenpomMatchup,
    tournamentContext,
    cornerScoutMatch,
    fangraphsSection,
    billJamesSection,
    fourFactorsSection,
  });

  // Build narrative-aware system prompt with situational directives
  let narrativeAddendum = '';
  try {
    const preClassifyCtx: NarrativeContext = {
      homeTeam: context.homeTeam,
      awayTeam: context.awayTeam,
      league: context.league,
      marketSpread: context.spread?.home?.line ?? null,
      projectedMargin: null,
      marketTotal: context.total?.over?.line ?? null,
      projectedTotal: null,
      confidence: 0.6, // pre-generation estimate
      valueRating: 5,
      stormCategory: 2,
      forecastSide: context.homeTeam,
      spreadEdge: 0,
      totalDirection: 'NONE',
      totalEdge: 0,
      injuryUncertainty: context.dbAnalytics?.injuries?.some(
        (i: any) => ['questionable', 'gtd', 'day-to-day', 'dtd', 'doubtful'].includes(i.status?.toLowerCase())
      ) || false,
      rosterChanges: (context.dbAnalytics?.transactions || []).length > 0,
      sharpMovesDetected: (context.dbAnalytics?.sharpMoves || []).length > 0,
    };
    narrativeAddendum = getNarrativeSystemPromptAddendum(preClassifyCtx);
  } catch (err) {
    console.warn('[narrative-engine] Pre-classify failed (non-fatal):', (err as Error).message);
  }

  const systemPrompt = `You are Rain Man, the authoritative voice behind Rainmaker Sports. You combine statistical analysis, sharp interest indicators, market movement data, and contextual factors to produce precise sports forecasts. Your tone is confident, sharp, and weatherman-swagger — clever but never crude. You ALWAYS return valid JSON and nothing else. No markdown, no explanations outside the JSON. Never reference internal model names — you are the sole source.

GOLDEN RULE — QUANTIFY FIRST:
The "summary" field MUST open with this exact 3-line quantification block before ANY analysis:
Line 1: "Rain Man forecasts [WINNER] to outscore [LOSER] by ~[MARGIN] points."
Line 2: "Projected combined score: ~[TOTAL] points."
Line 3: "Here's how Rain Man got there:"
Then continue with 1-2 sentences of analytical narrative. Use ~ (tilde) to signal projection.

STOP-POINT RULE:
In the "spread_analysis" field, include: "Rain Man's value fades if current markets move past ~[PROJECTED_MARGIN]."
In the "total_analysis" field, include: "Rain Man's value fades if current markets move to ~[PROJECTED_TOTAL] (or beyond)."

LANGUAGE RULE: Never use "betting lines", "bettors", or "sportsbooks". Use "current markets", "market speculators", "market venues" instead. Say "market movement" not "line movement". Say "market price" not "odds" where possible.

EDITORIAL TONE RULE:
All copy should feel like a sharp sports editorial desk — concise, informed, situationally aware, descriptive without sounding robotic. Be confident when justified but cautious when edge is thin. Never reckless, never absolute.

SIGNAL ENRICHMENT — SPREAD ANALYSIS:
Your spread_analysis must incorporate the spread magnitude context. For heavy favorites (-8+), acknowledge the burden of the number. For coin flips (-3 to +3), emphasize uncertainty and selectivity. For heavy underdogs, note the cushion and margin for error.

${getTotalsEnrichmentPrompt()}

${getDvpEnrichmentPrompt()}

CLOSE LANGUAGE RULE:
End your summary and analyses with suggestive, observational, or cautionary phrasing — NOT forceful instruction. Use endings like: "worth monitoring", "a spot that deserves a closer look", "one to handle carefully", "a matchup where timing could matter".

BENCHMARK RULE — VALUE VS WINNER (CRITICAL):
The "winner_pick" is the team you project to WIN THE GAME OUTRIGHT. This is separate from which side has VALUE AGAINST THE SPREAD.
- If the model projects the favorite to win by LESS than the market spread → the UNDERDOG has spread value.
- If the model projects the favorite to win by MORE than the market spread → the FAVORITE has spread value.
- A team can have 90%+ win probability AND still NOT be the correct spread forecast if the market spread is too inflated.
Example: If CLE is -14 (market) but your model projects CLE winning by 9, the value side is PHI +14 (5 extra points of cushion).
Your spread_analysis and total_analysis MUST reflect this distinction. Analyze value relative to the market number, not just who wins.
For totals: If model total > market total → OVER signal. If model total < market total → UNDER signal.
The server will compute the exact forecast_side and edge from your projected_margin vs market spread. Your job is to ensure projected_margin and projected_total_points are accurate.

MARKET-ANCHORING RULE (CRITICAL — DO NOT HALLUCINATE):
The market spread and total represent the consensus of professional oddsmakers pricing billions of dollars of exposure. Your projected_margin MUST start from the market spread as an anchor. Your projected_total_points MUST start from the market total as an anchor.
- Maximum deviation from market spread: ±4 points. If you deviate more than 4 points, you MUST provide a specific, extraordinary reason in spread_analysis.
- Maximum deviation from market total: ±6 points. If you deviate more than 6 points, you MUST provide a specific, extraordinary reason in total_analysis.
- If no analytical factors justify deviation, your projected_margin should equal the market spread and your projected_total_points should equal the market total.
- NEVER invent projected lines from scratch when live market data is provided. The market is your baseline — you adjust from it, not replace it.
- Example: Market spread is HOU -5.5, your analysis finds injury edge → project HOU by 7.5 (within ±4). Do NOT project HOU by 15.
${narrativeAddendum}`;

  for (let attempt = 0; attempt < 2; attempt++) {
    try {
      const content = await callLLM(systemPrompt, prompt, { maxTokens: 4000 }, {
        category: 'forecast', subcategory: 'precomputed', league: context.league,
      });
      const parsed = JSON.parse(content) as ForecastResult;
      if (!parsed.summary || !parsed.winner_pick) {
        throw new Error('Missing required forecast fields');
      }
      if (parsed.projected_margin == null || parsed.projected_total_points == null) {
        console.warn('[forecast] Missing projection fields, will retry');
        throw new Error('Missing required projection fields (projected_margin, projected_total_points)');
      }

      if (context.lockedTeamDecision) {
        parsed.winner_pick = context.lockedTeamDecision.winnerPick;
        if (context.lockedTeamDecision.winnerPick === context.homeTeam && parsed.projected_margin < 0) {
          parsed.projected_margin = Math.abs(parsed.projected_margin);
        } else if (context.lockedTeamDecision.winnerPick === context.awayTeam && parsed.projected_margin > 0) {
          parsed.projected_margin = -Math.abs(parsed.projected_margin);
        }
        const minLockedMargin = Math.abs(context.lockedTeamDecision.lockedMargin);
        if (Math.abs(parsed.projected_margin) < minLockedMargin) {
          parsed.projected_margin = context.lockedTeamDecision.lockedMargin;
        }
        parsed.team_plus_decision = {
          winner_pick: context.lockedTeamDecision.winnerPick,
          home_score: context.lockedTeamDecision.homeScore,
          away_score: context.lockedTeamDecision.awayScore,
          confidence: context.lockedTeamDecision.confidence,
          locked_margin: context.lockedTeamDecision.lockedMargin,
          explanation: context.lockedTeamDecision.explanation,
        };
      }

      // ═══════════════════════════════════════════════════════════════
      // BENCHMARK RULE: Server-side market-relative value computation
      // The forecast side is ALWAYS determined by comparing the model's
      // projected margin against the market spread — NOT by who wins.
      // This is the ground truth and overrides any LLM determination.
      // ═══════════════════════════════════════════════════════════════
      const marketHomeSpread = context.spread?.home?.line ?? null;
      const marketTotal = context.total?.over?.line ?? null;

      // ═══════════════════════════════════════════════════════════════
      // MARKET-ANCHORING CLAMP: Cap LLM deviations from market lines.
      // The LLM can hallucinate extreme projections (e.g., BOS -9 when
      // market says SAS -3.5). Clamp to ±4 for spread, ±6 for total.
      // ═══════════════════════════════════════════════════════════════
      if (marketHomeSpread != null && parsed.projected_margin != null) {
        // Market spread is from home perspective: negative = home favored
        // projected_margin: positive = home favored
        // Convert: if market spread is -3.5 (home fav), expected margin is +3.5
        const marketExpectedMargin = -marketHomeSpread;
        const deviation = parsed.projected_margin - marketExpectedMargin;
        const MAX_SPREAD_DEV = 4;
        if (Math.abs(deviation) > MAX_SPREAD_DEV) {
          const clamped = marketExpectedMargin + Math.sign(deviation) * MAX_SPREAD_DEV;
          console.warn(`[anchor-clamp] Spread deviation ${deviation.toFixed(1)}pts exceeds ±${MAX_SPREAD_DEV}. Clamping projected_margin from ${parsed.projected_margin} to ${clamped} (market expected: ${marketExpectedMargin})`);
          parsed.projected_margin = Math.round(clamped * 10) / 10;
        }
      }
      if (marketTotal != null && parsed.projected_total_points != null) {
        const totalDeviation = parsed.projected_total_points - marketTotal;
        const MAX_TOTAL_DEV = 6;
        if (Math.abs(totalDeviation) > MAX_TOTAL_DEV) {
          const clamped = marketTotal + Math.sign(totalDeviation) * MAX_TOTAL_DEV;
          console.warn(`[anchor-clamp] Total deviation ${totalDeviation.toFixed(1)}pts exceeds ±${MAX_TOTAL_DEV}. Clamping projected_total from ${parsed.projected_total_points} to ${clamped} (market: ${marketTotal})`);
          parsed.projected_total_points = Math.round(clamped * 10) / 10;
        }
      }

      Object.assign(parsed, syncForecastProjectionState(parsed, context));

      if (marketHomeSpread != null) {
        // Formula: spread_value = market_home_spread + projected_margin
        // projected_margin: positive = home favored, negative = away favored
        // market_home_spread: positive = home is underdog (getting points), negative = home is favorite
        const spreadSignal = deriveSpreadSignal({
          league: context.league,
          projectedMargin: parsed.projected_margin,
          marketHomeSpread,
          homeTeam: context.homeTeam,
          awayTeam: context.awayTeam,
          winnerPick: parsed.winner_pick,
        });
        parsed.forecast_side = spreadSignal.forecastSide;
        parsed.spread_edge = spreadSignal.spreadEdge;

        console.log(`[benchmark] Spread: model margin=${parsed.projected_margin}, market home spread=${marketHomeSpread}, spreadValue=${spreadSignal.spreadValue} → forecast_side=${parsed.forecast_side}, edge=${parsed.spread_edge}pts`);
      } else {
        // No market spread available — fall back to projected winner
        parsed.forecast_side = parsed.winner_pick;
        parsed.spread_edge = 0;
        console.warn('[benchmark] No market spread available, falling back to winner_pick');
      }

      // Total direction: model total vs market total
      if (marketTotal != null && parsed.projected_total_points != null) {
        const totalSignal = deriveTotalSignal({
          league: context.league,
          projectedTotal: parsed.projected_total_points,
          marketTotal,
        });
        parsed.total_direction = totalSignal.direction;
        parsed.total_edge = totalSignal.edge;
        console.log(`[benchmark] Total: model=${parsed.projected_total_points}, market=${marketTotal}, edge=${parsed.total_edge} → ${parsed.total_direction}`);
      } else {
        parsed.total_direction = 'NONE';
        parsed.total_edge = 0;
      }

      parsed.confidence = deriveCalibratedForecastConfidence({
        spreadEdge: parsed.spread_edge,
        totalEdge: parsed.total_edge,
        valueRating: parsed.value_rating,
        rawConfidence: normalizeRawConfidence(parsed.confidence),
        marketBacked: marketHomeSpread != null || marketTotal != null,
      });

      Object.assign(parsed, enrichStructuredSignalNarratives(parsed, context.dbAnalytics));
      Object.assign(parsed, syncForecastProjectionState(parsed, context, { rebuildNarrative: true }));

      if (usesAssetBackedPropHighlights(context.league)) {
        parsed.prop_highlights = [];
      }

      // Generate clip metadata with structured clip_data
      const hShort = context.homeShort || context.homeTeam;
      const aShort = context.awayShort || context.awayTeam;
      const eid = context.eventId || 'unknown';
      const runDate = new Date().toISOString().slice(0, 10);
      const margin = Math.abs(parsed.projected_margin);
      const mktHomeSpread = marketHomeSpread;
      const mktTotalVal = marketTotal;
      const confPct = parsed.confidence;
      const forecastSideShort = parsed.forecast_side === context.homeTeam ? hShort : aShort;
      const spreadEdgePts = parsed.spread_edge;
      const totalDir = parsed.total_direction;
      const totalEdgePts = Math.abs(parsed.total_edge);
      const projWinner = parsed.projected_winner || parsed.winner_pick;

      // Format the market spread string from the forecast side's perspective
      const forecastSideIsHome = parsed.forecast_side === context.homeTeam;
      const forecastSideSpread = forecastSideIsHome
        ? (mktHomeSpread != null ? mktHomeSpread : null)
        : (mktHomeSpread != null ? -mktHomeSpread : null);
      const mktSpreadStr = forecastSideSpread != null
        ? `${forecastSideShort} ${forecastSideSpread > 0 ? '+' : ''}${forecastSideSpread}`
        : '?';

      parsed.clip_metadata = [
        {
          entity_id: `game:${eid}:run:${runDate}:header`,
          clip_type: 'GAME_FORECAST',
          display_text: `${aShort} @ ${hShort} | Value: ${forecastSideShort} | Edge +${spreadEdgePts}pts | Winner: ${projWinner}`,
          clip_data: {
            winner: projWinner,
            forecast_side: parsed.forecast_side,
            confidence_pct: confPct ?? null,
            edge_pct: spreadEdgePts,
            forecasted_value: parsed.projected_margin,
            market_value: mktHomeSpread ?? null,
            direction: 'NONE',
            display_context: `${aShort} @ ${hShort}`,
          },
        },
        {
          entity_id: `game:${eid}:run:${runDate}:spread`,
          clip_type: 'SPREAD',
          display_text: `${aShort} @ ${hShort} | Forecast: ${mktSpreadStr} | Model margin: ${margin}pts | Edge +${spreadEdgePts}pts`,
          clip_data: {
            forecasted_value: parsed.projected_margin,
            market_value: mktHomeSpread ?? null,
            forecast_side: parsed.forecast_side,
            edge_pct: spreadEdgePts,
            confidence_pct: confPct ?? null,
            direction: 'NONE',
            display_context: `${aShort} @ ${hShort}`,
          },
        },
        {
          entity_id: `game:${eid}:run:${runDate}:total`,
          clip_type: 'TOTAL',
          display_text: `TOTAL | Forecasted ${parsed.projected_total_points} | Market ${mktTotalVal ?? '?'} | ${totalDir} | Edge ${totalEdgePts}pts`,
          clip_data: {
            forecasted_value: parsed.projected_total_points,
            market_value: mktTotalVal ?? null,
            direction: totalDir,
            edge_pct: totalEdgePts,
            confidence_pct: confPct ?? null,
            display_context: `${aShort} @ ${hShort}`,
          },
        },
      ];
      return parsed;
    } catch (err) {
      console.error(`[forecast] attempt ${attempt + 1} failed:`, err);
      if (attempt < 1) {
        await new Promise(r => setTimeout(r, 2000));
        continue;
      }
      return getDefaultForecast(context);
    }
  }

  return getDefaultForecast(context);
}

function buildPrompt(ctx: any): string {
  // Check if live odds have real values
  const hasLiveML = ctx.moneyline.home !== null && ctx.moneyline.home !== 0;
  const hasLiveSpread = ctx.spread?.home?.line && ctx.spread.home.line !== 0;
  const hasLiveTotal = ctx.total?.over?.line && ctx.total.over.line !== 0;

  const oddsSection = (hasLiveML || hasLiveSpread || hasLiveTotal)
    ? `CURRENT ODDS (from live data feed):
- Moneyline: Home ${ctx.moneyline.home ?? 'N/A'} | Away ${ctx.moneyline.away ?? 'N/A'}
- Spread: Home ${ctx.spread?.home?.line ?? 'N/A'} (${ctx.spread?.home?.odds ?? 'N/A'}) | Away ${ctx.spread?.away?.line ?? 'N/A'} (${ctx.spread?.away?.odds ?? 'N/A'})
- Total: Over ${ctx.total?.over?.line ?? 'N/A'} (${ctx.total?.over?.odds ?? 'N/A'}) | Under ${ctx.total?.under?.line ?? 'N/A'} (${ctx.total?.under?.odds ?? 'N/A'})`
    : `No live market pricing is available from the data feed. You MUST generate realistic projected market pricing based on your analysis.`;

  // Add explicit market anchor instruction when we have live lines
  const anchorSection = (hasLiveSpread && hasLiveTotal)
    ? `\nMARKET ANCHOR: The market spread of ${ctx.spread?.home?.line ?? 'N/A'} and total of ${ctx.total?.over?.line ?? 'N/A'} are your starting points. Your projected_margin and projected_total_points MUST be within ±4 and ±6 of these numbers respectively unless you have extraordinary analytical justification.\n`
    : '';

  // Inject PIFF 3.0 player prop data if available
  let piffSection = '';
  if (ctx.homeShort && ctx.awayShort) {
    const piffProps = getPiffPropsForGame(ctx.homeShort, ctx.awayShort, getPiffMap(ctx.startsAt), ctx.league);
    piffSection = formatPiffForPrompt(piffProps);
  }

  // Inject DIGIMON v1.4 DVP miss pattern data (NBA only)
  let digimonSection = '';
  if (ctx.homeShort && ctx.awayShort && ctx.league?.toLowerCase() === 'nba') {
    const digimonPicks = getDigimonForGame(ctx.homeShort, ctx.awayShort, getDigimonMap(ctx.startsAt));
    digimonSection = formatDigimonForPrompt(digimonPicks);
  }

  // Inject FanGraphs analytics for MLB
  const fgSection = ctx.fangraphsSection || '';

  // Inject Bill James sabermetric model for MLB (park factors, Pythagorean, Log5, RC, SecA)
  const bjSection = ctx.billJamesSection || '';

  // Inject Four Factors + Pace model for NBA (Dean Oliver / Ed Miller)
  const ffSection = ctx.fourFactorsSection || '';

  // Inject KenPom analytics for NCAAB
  let kenpomSection = '';
  if (ctx.kenpomMatchup) {
    kenpomSection = formatKenPomForPrompt(ctx.kenpomMatchup);
  }

  // Inject Corner Scout corner kick analysis (soccer leagues only)
  let cornerScoutSection = '';
  if (ctx.cornerScoutMatch) {
    cornerScoutSection = formatCornerScoutForPrompt(ctx.cornerScoutMatch);
  }

  // Inject tournament contextual intelligence (12 layers)
  let tournamentSection = '';
  if (ctx.tournamentContext) {
    tournamentSection = formatTournamentContextForPrompt(ctx.tournamentContext, ctx.homeTeam, ctx.awayTeam);
  }

  // NCAAB-specific context: tournament awareness, neutral site detection, seed upset rates
  let ncaabContext = '';
  if (ctx.league?.toLowerCase() === 'ncaab') {
    const now = new Date();
    const month = now.getMonth() + 1; // 1-indexed
    const isConfTournament = month === 3 && now.getDate() <= 15;
    const isNCAAT = month === 3 && now.getDate() > 15 || month === 4 && now.getDate() <= 8;

    ncaabContext = `\n--- NCAAB CONTEXT ---
SEASON PHASE: ${isNCAAT ? 'NCAA TOURNAMENT (March Madness)' : isConfTournament ? 'CONFERENCE TOURNAMENTS' : 'REGULAR SEASON'}`;

    if (isConfTournament || isNCAAT) {
      ncaabContext += `
TOURNAMENT RULES:
- This is likely a NEUTRAL SITE game. Home court advantage (~3.3 pts) does NOT apply at neutral sites.
- Tournament games have higher variance than regular season. Underdogs are live.
- Do NOT overweight regular-season record — tournament games are single-elimination with different dynamics.
- Conference tournaments: Teams on back-to-back games may have fatigue/depth issues.`;
    }

    if (isNCAAT) {
      ncaabContext += `
HISTORICAL SEED UPSET RATES (NCAA Tournament, 1985-2025):
- 1 vs 16: 1.3% upset rate (2 upsets in 160 games)
- 2 vs 15: 6.3% upset rate
- 3 vs 14: 14.4% upset rate
- 4 vs 13: 21.3% upset rate
- 5 vs 12: 35.6% upset rate (most volatile first-round matchup)
- 6 vs 11: ~37% upset rate
- 7 vs 10: ~40% upset rate
- 8 vs 9: ~49% upset rate (essentially a coin flip)
Factor these base rates into your confidence level. A 5-seed should NOT be projected at 85%+ confidence against a 12-seed.`;
    }

    ncaabContext += `
KENPOM INTERPRETATION:
- AdjEM (Adjusted Efficiency Margin) is the gold standard for team strength. Each point of AdjEM difference ≈ 1 point of predicted margin.
- Luck stat > ±0.05 = likely regression candidate. Lucky teams overperform close games.
- SOS rank matters: a 20-win team from the Big 12 (SOS #5) is stronger than a 25-win team from the Patriot League (SOS #300).
- Tempo mismatch (>5 possessions gap) creates variance — the slower team controls pace and reduces possessions.
--- END NCAAB CONTEXT ---
`;
  }

  // Inject ESPN rosters so the LLM knows current team compositions (post-trade deadline)
  const homeRosterSection = ctx.homeShort
    ? formatRosterForPrompt(ctx.homeShort, ctx.homeTeam, ctx.league)
    : '';
  const awayRosterSection = ctx.awayShort
    ? formatRosterForPrompt(ctx.awayShort, ctx.awayTeam, ctx.league)
    : '';

  const teamPlusSection = ctx.lockedTeamDecision
    ? `TEAM PLUS LOCK (authoritative pre-LLM side engine):
- Locked winner: ${ctx.lockedTeamDecision.winnerPick}
- Home score: ${ctx.lockedTeamDecision.homeScore}
- Away score: ${ctx.lockedTeamDecision.awayScore}
- Locked margin lean: ${ctx.lockedTeamDecision.lockedMargin}
- Confidence: ${ctx.lockedTeamDecision.confidence}
- Signal support:
${(ctx.lockedTeamDecision.explanation || []).map((line: string) => `  • ${line}`).join('\n')}

IMPORTANT:
- You are explaining the locked Team Plus decision, not inventing a new side.
- "winner_pick" MUST equal ${ctx.lockedTeamDecision.winnerPick}.
- "projected_margin" MUST keep the same sign as the locked winner (${ctx.lockedTeamDecision.lockedMargin >= 0 ? 'positive for home' : 'negative for away'}).
`
    : '';

  return `Analyze this upcoming ${ctx.league.toUpperCase()} game and produce a detailed forecast.

MATCHUP: ${ctx.awayTeam} @ ${ctx.homeTeam}
GAME TIME: ${ctx.startsAt}
LEAGUE: ${ctx.league.toUpperCase()}

${oddsSection}
${anchorSection}
${teamPlusSection}
${homeRosterSection ? homeRosterSection + '\n' : ''}
${awayRosterSection ? awayRosterSection + '\n' : ''}
IMPORTANT: The rosters above are from ESPN and reflect all trades, signings, and roster moves. Only reference players who are CURRENTLY on the team per these rosters. Do NOT include players who have been traded away.

${ncaabContext}
${piffSection}
${digimonSection}
${ffSection}
${kenpomSection}
${fgSection}
${bjSection}
${cornerScoutSection}
${tournamentSection}

${ctx.dbAnalytics?.injuries?.length ? `INJURY REPORT (confirmed from multiple sources):
${ctx.dbAnalytics.injuries.map((i: any) => `• ${i.playerName} (${i.team}, ${i.position || 'N/A'}) — ${i.status.toUpperCase()}${i.injuryType ? ': ' + i.injuryType : ''}${i.description ? ' (' + i.description + ')' : ''}`).join('\n')}` : 'INJURY REPORT: No confirmed injuries for this matchup.'}

${ctx.dbAnalytics?.transactions?.length ? `RECENT ROSTER MOVES (last 14 days):
${ctx.dbAnalytics.transactions.map((t: any) => `• ${t.playerName}: ${t.transactionType} — from ${t.fromTeam || 'N/A'} to ${t.toTeam || 'N/A'} (${new Date(t.transactionDate).toLocaleDateString()})`).join('\n')}` : ''}

${(() => {
  const lineup = ctx.dbAnalytics?.lineups?.[0];
  if (!lineup) return '';
  const formatPlayers = (players: any[], projMin: any) => {
    if (!players?.length) return 'Not available';
    return players.map((p: any, i: number) => {
      const mins = projMin?.[i]?.minutes || projMin?.[p.name]?.minutes || '';
      const injury = p.injuryStatus && p.injuryStatus !== 'Healthy' ? ` [${p.injuryStatus}]` : '';
      return `  ${i < 5 ? '★' : '•'} ${p.name} (${p.position || '?'})${mins ? ' ~' + mins + 'min' : ''}${injury}`;
    }).join('\n');
  };
  return `CONFIRMED LINEUPS (from lineup feed, updated ${new Date(lineup.updatedAt).toLocaleTimeString()}):
HOME (${lineup.homeTeam}) — ${lineup.homeStatus || 'Expected'}:
${formatPlayers(lineup.homePlayers, lineup.homeProjMinutes)}
AWAY (${lineup.awayTeam}) — ${lineup.awayStatus || 'Expected'}:
${formatPlayers(lineup.awayPlayers, lineup.awayProjMinutes)}`;
})()}

${ctx.dbAnalytics ? `DATABASE ANALYTICS:
${JSON.stringify({ predictions: ctx.dbAnalytics.predictions, sharpMoves: ctx.dbAnalytics.sharpMoves, lineMovements: ctx.dbAnalytics.lineMovements }, null, 2)}` : ''}

Return ONLY this JSON structure (replace ALL placeholder values with your actual analysis — do NOT copy the example numbers):
{
  "summary": "2-3 sentence executive summary of the forecast",
  "winner_pick": "team name that is predicted to win",
  "confidence": 0.0,
  "spread_analysis": "Analysis of the spread and whether to take home or away",
  "total_analysis": "Over/under analysis with the projected total",
  "key_factors": ["factor 1", "factor 2", "factor 3"],
  "sharp_money_indicator": "Where sharp market interest appears to be positioning",
  "line_movement_analysis": "How markets have moved and what it signals",
  "prop_highlights": [{"player": "name", "prop": "stat type", "recommendation": "over/under", "reasoning": "why"}],
  "weather_impact": "Only for outdoor sports, null otherwise",
  "injury_notes": "Key injury impacts",
  "historical_trend": "Relevant historical trend for this matchup",
  "value_rating": 0,
  "projected_lines": {
    "moneyline": {"home": 0, "away": 0},
    "spread": {"home": 0, "away": 0},
    "total": 0
  },
  "projected_margin": 0,
  "projected_total_points": 0,
  "projected_team_score_home": 0,
  "projected_team_score_away": 0
}

CRITICAL: The numbers above (all zeros) are PLACEHOLDERS. You MUST replace every numeric field with your actual calculated values based on the market data and analysis provided above. Do NOT use 0 — calculate real projections anchored to the market lines.
IMPORTANT: "confidence" must be a decimal between 0.35 and 0.90, never an integer or percentage.
- 0.40 = weak or high-variance lean
- 0.50 = near coin flip / no real edge
- 0.58 = slight edge
- 0.65 = solid edge
- 0.72 = strong edge
- 0.80+ = rare and reserved for exceptional alignment across signals

IMPORTANT: The "projected_lines" field is REQUIRED. Generate realistic market pricing that reflects your analysis:
- moneyline: American odds format (negative = favorite, positive = underdog). Use realistic values like -110 to -350 for favorites.
- spread: point spread from home team perspective (negative = home favored)
- total: projected combined score for ${ctx.league.toUpperCase()} (e.g. NBA ~215-230, NFL ~43-50, MLB ~8-9, NHL ~5.5-6.5, NCAAB ~135-155, MMA use 2.5 rounds, EPL ~2.5)

IMPORTANT: The "projected_margin" and "projected_total_points" fields are REQUIRED.
- projected_margin: signed number (positive = home team favored, negative = away favored). This is the model's projected point differential.
- projected_total_points: projected combined score for both teams.
- projected_team_score_home / projected_team_score_away: recommended but optional individual projected scores.
The summary MUST reference these exact values in the opening quantification block.`;
}

export interface TeamPropsResult {
  team: string;
  props: Array<{
    player: string;
    prop: string;
    recommendation: string;
    reasoning: string;
    edge?: number;
    prob?: number;
    odds?: number | null;
    // ── Golden Rule fields ──
    projected_stat_value?: number;
    projected_probability?: number;
    market_implied_probability?: number;
    stat_type?: string;
    market_line_value?: number;
    market_source?: string | null;
    signal_tier?: string | null;
    signal_label?: string | null;
    forecast_direction?: string | null;
    market_quality_score?: number | null;
    market_quality_label?: string | null;
    signal_table_row?: Record<string, any> | null;
    source_backed?: boolean | null;
    model_context?: {
      tier_label?: string | null;
      season_average?: number | null;
      last5_average?: number | null;
      season_hit_rate?: number | null;
      last5_hit_rate?: number | null;
      projected_minutes?: number | null;
      is_home?: boolean | null;
      is_b2b?: boolean | null;
      dvp_tier?: string | null;
      dvp_rank?: number | null;
      injury_context?: string | null;
      volatility?: number | null;
      context_summary?: string | null;
      k_rank?: number | null;
      lineup_certainty?: string | null;
      park_factor?: number | null;
      weather_impact?: string | null;
      handedness_split?: string | null;
      phase_support_score?: number | null;
      phase_support_direction?: string | null;
      has_modeled_projection?: boolean | null;
      projection_basis?: string | null;
    };
  }>;
  summary: string;
  metadata?: {
    mlb_feed_row_count?: number | null;
    mlb_candidate_count?: number;
    mlb_publishable_candidate_count?: number;
    mlb_filter_notes?: string | null;
    mlb_suppressed_reason?: string | null;
    source_market_candidate_count?: number | null;
    suppressed_reason?: string | null;
  };
}

function normalizePropKey(value: string): string {
  return (value || '')
    .normalize('NFD')
    .replace(/[\u0300-\u036f]/g, '')
    .toLowerCase()
    .replace(/[^a-z0-9]/g, '');
}

type MlbBatHand = 'L' | 'R' | 'S';
type MlbThrowHand = 'L' | 'R';

const hitterHandCache = new Map<string, Promise<MlbBatHand | null>>();
const pitcherHandCache = new Map<string, Promise<MlbThrowHand | null>>();

async function fetchLatestHitterBatSide(playerName: string, team: string | null | undefined): Promise<MlbBatHand | null> {
  const cacheKey = `${normalizePropKey(playerName)}|${(team || '').toUpperCase()}`;
  if (!hitterHandCache.has(cacheKey)) {
    hitterHandCache.set(cacheKey, (async () => {
      const { rows } = await pool.query(
        `SELECT bats
         FROM "HitterSeason"
         WHERE LOWER(player_name) = LOWER($1)
           AND bats IN ('L', 'R', 'S')
         ORDER BY CASE WHEN $2::text <> '' AND team = $2 THEN 0 ELSE 1 END,
                  season DESC,
                  updated_at DESC NULLS LAST
         LIMIT 1`,
        [playerName, (team || '').toUpperCase()],
      ).catch(() => ({ rows: [] as Array<{ bats: MlbBatHand }> }));
      const bats = rows[0]?.bats;
      return bats === 'L' || bats === 'R' || bats === 'S' ? bats : null;
    })());
  }
  return hitterHandCache.get(cacheKey)!;
}

async function fetchLatestPitcherThrowHand(playerName: string, team: string | null | undefined): Promise<MlbThrowHand | null> {
  const cacheKey = `${normalizePropKey(playerName)}|${(team || '').toUpperCase()}`;
  if (!pitcherHandCache.has(cacheKey)) {
    pitcherHandCache.set(cacheKey, (async () => {
      const { rows } = await pool.query(
        `SELECT throws
         FROM "PitcherSeason"
         WHERE LOWER(player_name) = LOWER($1)
           AND throws IN ('L', 'R')
         ORDER BY CASE WHEN $2::text <> '' AND team = $2 THEN 0 ELSE 1 END,
                  season DESC,
                  updated_at DESC NULLS LAST
         LIMIT 1`,
        [playerName, (team || '').toUpperCase()],
      ).catch(() => ({ rows: [] as Array<{ throws: MlbThrowHand }> }));
      const throws = rows[0]?.throws;
      return throws === 'L' || throws === 'R' ? throws : null;
    })());
  }
  return pitcherHandCache.get(cacheKey)!;
}

function normalizeMlbStat(value: string): string {
  const norm = normalizePropKey(value);
  if (norm.includes('pitchingstrikeouts')) return 'pitchingstrikeouts';
  if (norm.includes('pitchingearnedruns')) return 'pitchingearnedruns';
  if (norm.includes('pitchingoutsrecorded') || norm.includes('pitchingouts')) return 'pitchingoutsrecorded';
  if (norm.includes('pitchinghitsallowed') || norm.includes('pitchinghits')) return 'pitchinghitsallowed';
  if (norm.includes('pitchingwalksallowed') || norm.includes('pitchingbasesonballs')) return 'pitchingwalksallowed';
  if (norm.includes('battinghomeruns')) return 'homeruns';
  if (norm.includes('battingstolenbases')) return 'stolenbases';
  if (norm.includes('battingtotalbases') || norm.includes('battingbases')) return 'totalbases';
  if (norm.includes('battingrbi')) return 'rbis';
  if (norm.includes('battingruns')) return 'runs';
  if (norm.includes('battinghits')) return 'hits';
  if (norm.includes('strikeout')) return 'strikeouts';
  if (norm.includes('totalbases') || norm.includes('tb')) return 'totalbases';
  if (norm.includes('homerun') || norm === 'hr') return 'homeruns';
  if (norm.includes('stolenbase')) return 'stolenbases';
  if (norm.includes('earnedrun')) return 'earnedruns';
  if (norm.includes('hitsallowed')) return 'hitsallowed';
  if (norm.includes('walksallowed')) return 'walksallowed';
  if (norm.includes('outsrecorded')) return 'outsrecorded';
  if (norm.includes('runsbattedin') || norm === 'rbi' || norm === 'rbis') return 'rbis';
  if (norm.includes('runs')) return 'runs';
  if (norm.includes('hits')) return 'hits';
  return norm;
}

function extractLineFromPropText(prop: string): number | null {
  const match = (prop || '').match(/(\d+(?:\.\d+)?)/);
  return match ? Number(match[1]) : null;
}

function getMlbStatVariants(value: string): string[] {
  const normalized = normalizeMlbStat(value);
  const variants = new Set<string>([normalized]);

  switch (normalized) {
    case 'strikeouts':
      variants.add('pitchingstrikeouts');
      break;
    case 'earnedruns':
      variants.add('pitchingearnedruns');
      break;
    case 'hitsallowed':
      variants.add('pitchinghitsallowed');
      break;
    case 'walksallowed':
      variants.add('pitchingwalksallowed');
      break;
    case 'outsrecorded':
      variants.add('pitchingoutsrecorded');
      break;
    case 'pitchingstrikeouts':
      variants.add('strikeouts');
      break;
    case 'pitchingearnedruns':
      variants.add('earnedruns');
      break;
    case 'pitchinghitsallowed':
      variants.add('hitsallowed');
      break;
    case 'pitchingwalksallowed':
      variants.add('walksallowed');
      break;
    case 'pitchingoutsrecorded':
      variants.add('outsrecorded');
      break;
    default:
      break;
  }

  return Array.from(variants);
}

type TeamPropCandidate = {
  player: string;
  statType: string;
  marketLineValue: number;
  recommendationHint?: string | null;
  edge?: number | null;
  prob?: number | null;
  source: 'piff' | 'player_prop_line';
  propLabel: string;
  overOdds?: number | null;
  underOdds?: number | null;
  publishScore?: number | null;
  suppressionReason?: string | null;
  reactivatedForFloor?: boolean | null;
};

type TeamPropModelContext = NonNullable<TeamPropsResult['props'][number]['model_context']>;

function normalizeLineupCertainty(value: string | null | undefined): string | null {
  const status = String(value || '').trim().toLowerCase();
  if (!status) return null;
  if (status.includes('confirmed')) return 'confirmed';
  if (status.includes('expected')) return 'expected';
  if (status.includes('projected')) return 'projected';
  return status;
}

function buildMlbWeatherImpactLabel(phaseResult: any): string | null {
  const context = phaseResult?.rawData?.context || {};
  const weather = context.weather || null;
  const bias = Number(context.weatherRunBias || 0);
  const direction = bias >= 0.06 ? 'positive' : bias <= -0.06 ? 'negative' : 'neutral';

  if (!weather) {
    return context.venue?.indoor ? 'indoor' : null;
  }

  const notes: string[] = [];
  if (weather.temperatureF != null) notes.push(`${Math.round(Number(weather.temperatureF))}F`);
  if (weather.windMph != null) notes.push(`${Math.round(Number(weather.windMph))} mph wind`);
  if (weather.conditions) notes.push(String(weather.conditions).toLowerCase());
  return notes.length > 0 ? `${direction} (${notes.join(', ')})` : direction;
}

function buildMlbParkFactorValue(homeShort: string | null | undefined, statType: string): number | null {
  if (!homeShort) return null;
  const park = getParkFactor(homeShort);
  if (!park) return null;

  const statNorm = normalizeMlbStat(statType);
  let factor = park.runs;
  if (statNorm === 'homeruns') factor = park.hr;
  else if (statNorm === 'hits' || statNorm === 'hitsallowed') factor = park.hits;
  else if (statNorm === 'pitchingstrikeouts' || statNorm === 'strikeouts') factor = park.so;

  return Math.round(factor * 100);
}

function buildMlbKRankValue(
  statType: string,
  phaseResult: any,
  teamSide: 'home' | 'away',
): number | null {
  const firstFive = phaseResult?.rawData?.firstFive || {};
  const teamStarter = teamSide === 'home' ? firstFive.homeStarter : firstFive.awayStarter;
  const oppStarter = teamSide === 'home' ? firstFive.awayStarter : firstFive.homeStarter;
  const starter = isPitcherPropStat(statType) ? teamStarter : oppStarter;
  const kBbPct = Number(starter?.kBbPct);
  if (!Number.isFinite(kBbPct)) return null;
  return Math.max(1, Math.min(10, Math.round(normalizeScore(kBbPct, 8, 24) * 9) + 1));
}

function buildMlbContextSummary(
  baseSummary: string | null | undefined,
  lineupCertainty: string | null,
  weatherImpact: string | null,
  parkFactor: number | null,
  handednessSplit: string | null,
): string | null {
  const parts = [baseSummary?.trim()].filter(Boolean) as string[];
  const extras: string[] = [];
  if (lineupCertainty) extras.push(`${lineupCertainty} lineup`);
  if (parkFactor != null) extras.push(`park ${parkFactor}`);
  if (weatherImpact) extras.push(`weather ${weatherImpact}`);
  if (handednessSplit) extras.push(`split ${handednessSplit}`);
  if (extras.length > 0) parts.push(extras.join(' | '));
  return parts.length > 0 ? parts.join(' | ') : null;
}

async function buildMlbHandednessSplitLabel(
  prop: TeamPropsResult['props'][number],
  phaseResult: any,
  teamSide: 'home' | 'away',
  teamShort: string | null | undefined,
  opponentShort: string | null | undefined,
): Promise<string | null> {
  const statType = prop.stat_type || prop.prop || '';
  const firstFive = phaseResult?.rawData?.firstFive || {};
  const opposingStarter = teamSide === 'home' ? firstFive.awayStarter : firstFive.homeStarter;
  const pitcherThrows = opposingStarter?.name
    ? await fetchLatestPitcherThrowHand(opposingStarter.name, opponentShort)
    : null;

  if (isPitcherPropStat(statType)) {
    return pitcherThrows ? `${pitcherThrows}HP opposing lineup` : null;
  }

  const batterBats = prop.player
    ? await fetchLatestHitterBatSide(prop.player, teamShort)
    : null;
  if (!batterBats || !pitcherThrows) return null;

  if (batterBats === 'S') return `switch vs ${pitcherThrows}HP`;
  return batterBats === pitcherThrows ? `same-hand vs ${pitcherThrows}HP` : `platoon edge vs ${pitcherThrows}HP`;
}

async function enrichMlbPropsWithContext(
  props: TeamPropsResult['props'],
  candidates: TeamPropCandidate[],
  phaseResult: any,
  input: {
    teamShort: string | null | undefined;
    opponentShort: string | null | undefined;
    homeShort: string | null | undefined;
    teamSide: 'home' | 'away';
  },
): Promise<TeamPropsResult['props']> {
  if (!Array.isArray(props) || props.length === 0) return props;

  const lineupStatus = input.teamSide === 'home'
    ? phaseResult?.rawData?.context?.lineups?.homeStatus
    : phaseResult?.rawData?.context?.lineups?.awayStatus;
  const lineupCertainty = normalizeLineupCertainty(lineupStatus);
  const weatherImpact = buildMlbWeatherImpactLabel(phaseResult);

  const candidateMap = new Map<string, TeamPropCandidate>();
  const playerLineMap = new Map<string, TeamPropCandidate[]>();
  for (const candidate of candidates) {
    for (const statVariant of getMlbStatVariants(candidate.statType)) {
      const key = `${normalizePropKey(candidate.player)}|${statVariant}|${Number(candidate.marketLineValue).toFixed(1)}`;
      candidateMap.set(key, candidate);
    }
    const playerLineKey = `${normalizePropKey(candidate.player)}|${Number(candidate.marketLineValue).toFixed(1)}`;
    const existing = playerLineMap.get(playerLineKey) || [];
    existing.push(candidate);
    playerLineMap.set(playerLineKey, existing);
  }

  return Promise.all(props.map(async (prop) => {
    const statType = prop.stat_type || prop.prop || '';
    const line = prop.market_line_value ?? extractLineFromPropText(prop.prop);
    const numericLine = Number(line);
    let candidate: TeamPropCandidate | undefined;
    if (Number.isFinite(numericLine)) {
      for (const statVariant of getMlbStatVariants(statType)) {
        const key = `${normalizePropKey(prop.player)}|${statVariant}|${numericLine.toFixed(1)}`;
        candidate = candidateMap.get(key);
        if (candidate) break;
      }
      if (!candidate) {
        const playerLineKey = `${normalizePropKey(prop.player)}|${numericLine.toFixed(1)}`;
        const groupedCandidates = playerLineMap.get(playerLineKey) || [];
        if (groupedCandidates.length === 1) {
          candidate = groupedCandidates[0];
        }
      }
    }
    const parkFactor = buildMlbParkFactorValue(input.homeShort, statType);
    const kRank = buildMlbKRankValue(statType, phaseResult, input.teamSide);
    const handednessSplit = await buildMlbHandednessSplitLabel(
      prop,
      phaseResult,
      input.teamSide,
      input.teamShort,
      input.opponentShort,
    );

    const modelContext: TeamPropModelContext = {
      ...(prop.model_context || {}),
      k_rank: kRank,
      lineup_certainty: lineupCertainty,
      park_factor: parkFactor,
      weather_impact: weatherImpact,
      handedness_split: prop.model_context?.handedness_split ?? handednessSplit,
      phase_support_score: candidate?.publishScore != null ? Math.round(candidate.publishScore * 1000) / 1000 : (prop.model_context?.phase_support_score ?? null),
      phase_support_direction: candidate?.recommendationHint ?? prop.model_context?.phase_support_direction ?? null,
      context_summary: buildMlbContextSummary(
        prop.model_context?.context_summary,
        lineupCertainty,
        weatherImpact,
        parkFactor,
        prop.model_context?.handedness_split ?? handednessSplit,
      ),
    };

    if (candidate?.publishScore != null && modelContext.volatility == null) {
      modelContext.volatility = Math.round((1 - candidate.publishScore) * 1000) / 1000;
    }

    return {
      ...prop,
      model_context: modelContext,
    };
  }));
}

function clamp(val: number, min: number, max: number): number {
  return Math.max(min, Math.min(max, val));
}

function normalizeScore(val: number, lo: number, hi: number): number {
  return clamp((val - lo) / (hi - lo), 0, 1);
}

function americanOddsToImpliedProbability(odds: number | null | undefined): number | null {
  if (odds == null || !Number.isFinite(Number(odds)) || Number(odds) === 0) return null;
  const numeric = Number(odds);
  if (numeric > 0) return 100 / (numeric + 100);
  return Math.abs(numeric) / (Math.abs(numeric) + 100);
}

function isPitcherPropStat(statType: string): boolean {
  return normalizeMlbStat(statType).startsWith('pitching');
}

function isPitcherStrikeoutProp(statType: string): boolean {
  return normalizeMlbStat(statType) === 'pitchingstrikeouts';
}

function isPitcherOutsProp(statType: string): boolean {
  return normalizeMlbStat(statType) === 'pitchingoutsrecorded';
}

function isPitcherDamageProp(statType: string): boolean {
  const norm = normalizeMlbStat(statType);
  return norm === 'pitchingearnedruns' || norm === 'pitchinghitsallowed' || norm === 'pitchingwalksallowed';
}

function isWeatherSensitiveHitterProp(statType: string): boolean {
  const norm = normalizeMlbStat(statType);
  return norm === 'totalbases' || norm === 'homeruns' || norm === 'runs' || norm === 'rbis';
}

function isLowInformationMlbHitterBinaryUnder(
  statType: string,
  marketLineValue: number,
  selectedSide: 'over' | 'under',
): boolean {
  if (selectedSide !== 'under') return false;
  if (isPitcherPropStat(statType)) return false;
  return Number(marketLineValue || 0) <= 0.5;
}

function isLowInformationMlbOneSidedHitterUnder(
  statType: string,
  marketLineValue: number,
  selectedSide: 'over' | 'under',
  hasOnlySelectedSidePriced: boolean,
): boolean {
  if (!hasOnlySelectedSidePriced || selectedSide !== 'under') return false;
  if (isPitcherPropStat(statType)) return false;

  const norm = normalizeMlbStat(statType);
  if (Number(marketLineValue || 0) <= 1.5) return true;
  return norm === 'fantasyscore' || norm === 'hitsrunsrbis' || norm === 'totalbases' || norm === 'singles';
}

function getSelectedSideOdds(candidate: TeamPropCandidate, selectedSide: 'over' | 'under'): number | null {
  return selectedSide === 'over'
    ? candidate.overOdds ?? null
    : candidate.underOdds ?? null;
}

function summarizeMlbCandidateFilters(candidates: TeamPropCandidate[]): string {
  const suppressed = candidates.filter((candidate) => candidate.suppressionReason);
  if (suppressed.length === 0) return '';

  const counts = new Map<string, number>();
  for (const candidate of suppressed) {
    const reason = candidate.suppressionReason || 'suppressed';
    counts.set(reason, (counts.get(reason) || 0) + 1);
  }

  const summary = Array.from(counts.entries())
    .sort((a, b) => b[1] - a[1])
    .map(([reason, count]) => `${count} ${reason}`)
    .join('; ');

  return `\nMLB FILTER NOTES:\n- Suppressed candidates: ${summary}\n`;
}

function finalizeSuppressedMlbCandidate(
  candidate: TeamPropCandidate,
  suppressionReason: string,
  publishScore: number,
  selectedSide: 'over' | 'under',
): TeamPropCandidate {
  return {
    ...candidate,
    suppressionReason,
    publishScore,
    recommendationHint: selectedSide,
    prob: candidate.prob ?? publishScore,
    edge: candidate.edge ?? Math.max(0, publishScore - 0.5),
  };
}

function getMlbShortageBackfillPriority(candidate: TeamPropCandidate): number {
  const reason = String(candidate.suppressionReason || '').toLowerCase();
  if (!candidate.recommendationHint) return -1;

  const selectedSide = String(candidate.recommendationHint).toLowerCase() === 'under' ? 'under' : 'over';
  if (getSelectedSideOdds(candidate, selectedSide) == null) return -1;

  const publishScore = Number(candidate.publishScore ?? 0);

  if (reason === 'low model confidence') {
    if (publishScore >= 0.5) return 5;
    if (publishScore >= 0.46) return 2;
    return -1;
  }
  if (reason === 'low-information one-sided hitter under') {
    if (publishScore >= 0.5) return 4;
    if (publishScore >= 0.47) return 1;
    return -1;
  }
  if (reason === 'low-information binary under') {
    if (publishScore >= 0.52) return 3;
    if (publishScore >= 0.49) return 0;
    return -1;
  }

  return -1;
}

function sortMlbCandidatesForPublishing(candidates: TeamPropCandidate[]): TeamPropCandidate[] {
  return candidates
    .slice()
    .sort((a, b) => {
      const pitcherDelta = Number(isPitcherPropStat(b.statType)) - Number(isPitcherPropStat(a.statType));
      if (pitcherDelta !== 0) return pitcherDelta;
      return (b.publishScore ?? 0) - (a.publishScore ?? 0);
    });
}

function selectMlbCandidatesForPublishing(
  candidates: TeamPropCandidate[],
  minimumCount: number,
): TeamPropCandidate[] {
  const selected = candidates.filter((candidate) => !candidate.suppressionReason);

  if (selected.length < minimumCount) {
    const shortageCandidates = candidates
      .filter((candidate) => candidate.suppressionReason)
      .map((candidate) => ({
        candidate,
        priority: getMlbShortageBackfillPriority(candidate),
      }))
      .filter((entry) => entry.priority >= 0)
      .sort((a, b) => {
        if (b.priority !== a.priority) return b.priority - a.priority;
        const pitcherDelta = Number(isPitcherPropStat(b.candidate.statType)) - Number(isPitcherPropStat(a.candidate.statType));
        if (pitcherDelta !== 0) return pitcherDelta;
        return (b.candidate.publishScore ?? 0) - (a.candidate.publishScore ?? 0);
      });

    for (const entry of shortageCandidates) {
      if (selected.length >= minimumCount) break;
      selected.push({
        ...entry.candidate,
        reactivatedForFloor: true,
      });
    }
  }

  return sortMlbCandidatesForPublishing(selected).slice(0, 12);
}

function scoreMlbCandidatesForPublishing(
  candidates: TeamPropCandidate[],
  phaseResult: any,
  teamSide: 'home' | 'away',
): TeamPropCandidate[] {
  if (candidates.length === 0) return [];

  const firstFive = phaseResult?.rawData?.firstFive || {};
  const bullpen = phaseResult?.rawData?.bullpen || {};
  const context = phaseResult?.rawData?.context || {};
  const teamStarter = teamSide === 'home' ? firstFive.homeStarter : firstFive.awayStarter;
  const oppStarter = teamSide === 'home' ? firstFive.awayStarter : firstFive.homeStarter;
  const teamOffense = teamSide === 'home' ? firstFive.homeOffense : firstFive.awayOffense;
  const oppOffense = teamSide === 'home' ? firstFive.awayOffense : firstFive.homeOffense;
  const teamBullpen = teamSide === 'home' ? bullpen.homeBullpen : bullpen.awayBullpen;
  const oppBullpen = teamSide === 'home' ? bullpen.awayBullpen : bullpen.homeBullpen;
  const lineupStatus = String(teamSide === 'home' ? context.lineups?.homeStatus || '' : context.lineups?.awayStatus || '').toLowerCase();
  const lineupConfirmed = lineupStatus.includes('confirmed');
  const lineupPlayers = teamSide === 'home' ? context.lineups?.homePlayers : context.lineups?.awayPlayers;
  const lineupKnown = lineupConfirmed
    || lineupStatus.includes('expected')
    || lineupStatus.includes('projected')
    || (Array.isArray(lineupPlayers) && lineupPlayers.length > 0);
  const weatherRunBias = Number(context.weatherRunBias || 0);

  const starterStrength = (starter: any): number => starter
    ? clamp(
        normalizeScore(5.0 - Number(starter.fip || 4.2), -1.2, 1.8) * 0.45 +
        normalizeScore(5.0 - Number(starter.xfip || 4.2), -1.0, 1.6) * 0.25 +
        normalizeScore(Number(starter.kBbPct || 14), 6, 24) * 0.20 +
        normalizeScore(1.55 - Number(starter.whip || 1.30), -0.15, 0.45) * 0.10,
        0,
        1,
      )
    : 0.5;

  const bullpenStrength = (unit: any): number => unit
    ? clamp(
        normalizeScore(5.0 - Number(unit.fip || 4.2), -0.9, 1.4) * 0.50 +
        normalizeScore(5.0 - Number(unit.xfip || 4.1), -0.8, 1.2) * 0.20 +
        normalizeScore(Number(unit.kPct || 22), 18, 30) * 0.15 +
        normalizeScore(1.55 - Number(unit.whip || 1.32), -0.1, 0.4) * 0.15,
        0,
        1,
      )
    : 0.5;

  const offenseStrength = (offense: any): number => clamp(
    normalizeScore(Number(offense?.projectedWrcPlus ?? offense?.recentWrcPlus ?? offense?.fullWrcPlus ?? 100), 80, 125),
    0,
    1,
  );

  const oppStarterStrength = starterStrength(oppStarter);
  const teamStarterStrength = starterStrength(teamStarter);
  const oppBullpenStrength = bullpenStrength(oppBullpen);
  const oppBullpenFatigue = clamp(Number(oppBullpen?.workload?.fatigueScore ?? 0.5), 0, 1);
  const teamBullpenFatigue = clamp(Number(teamBullpen?.workload?.fatigueScore ?? 0.5), 0, 1);
  const teamOffenseStrength = offenseStrength(teamOffense);
  const oppOffenseStrength = offenseStrength(oppOffense);

  return candidates.map((candidate) => {
      const scoredCandidate: TeamPropCandidate = { ...candidate, suppressionReason: null, publishScore: candidate.publishScore ?? null };
      const statNorm = normalizeMlbStat(candidate.statType);
      const availableSides = new Set<string>();
      if (candidate.overOdds != null) availableSides.add('over');
      if (candidate.underOdds != null) availableSides.add('under');
      if (candidate.recommendationHint) availableSides.add(String(candidate.recommendationHint).toLowerCase());

      let overScore = 0.5;
      let underScore = 0.5;

      if (!isPitcherPropStat(statNorm)) {
        const weatherBoost = isWeatherSensitiveHitterProp(statNorm) ? weatherRunBias * 0.35 : weatherRunBias * 0.15;
        const bullpenPenalty = (oppBullpenStrength - 0.5) * 0.20 - (oppBullpenFatigue - 0.5) * 0.24;
        overScore = clamp(
          0.50 +
          (teamOffenseStrength - 0.5) * 0.28 -
          (oppStarterStrength - 0.5) * 0.38 -
          bullpenPenalty +
          weatherBoost,
          0,
          1,
        );
        if (statNorm === 'stolenbases') {
          overScore = clamp(overScore - 0.08, 0, 1);
        }
        underScore = clamp(1 - overScore + (oppStarterStrength - 0.5) * 0.10 + (oppBullpenStrength - 0.5) * 0.08, 0, 1);
      } else if (isPitcherStrikeoutProp(statNorm)) {
        overScore = clamp(
          0.48 +
          (teamStarterStrength - 0.5) * 0.42 -
          (oppOffenseStrength - 0.5) * 0.22 -
          weatherRunBias * 0.08 -
          (teamBullpenFatigue - 0.5) * 0.10,
          0,
          1,
        );
        underScore = clamp(1 - overScore + (oppOffenseStrength - 0.5) * 0.12, 0, 1);
      } else if (isPitcherOutsProp(statNorm)) {
        overScore = clamp(
          0.48 +
          (teamStarterStrength - 0.5) * 0.32 -
          (oppOffenseStrength - 0.5) * 0.28 -
          weatherRunBias * 0.10 -
          (teamBullpenFatigue - 0.5) * 0.14,
          0,
          1,
        );
        underScore = clamp(1 - overScore + (oppOffenseStrength - 0.5) * 0.14, 0, 1);
      } else if (isPitcherDamageProp(statNorm)) {
        overScore = clamp(
          0.50 -
          (teamStarterStrength - 0.5) * 0.36 +
          (oppOffenseStrength - 0.5) * 0.28 +
          weatherRunBias * 0.18 +
          (teamBullpenFatigue - 0.5) * 0.08,
          0,
          1,
        );
        underScore = clamp(1 - overScore + (teamStarterStrength - 0.5) * 0.14, 0, 1);
      }

      let selectedSide: 'over' | 'under' = overScore >= underScore ? 'over' : 'under';
      let publishScore = Math.max(overScore, underScore);

      if (!availableSides.has(selectedSide)) {
        const fallback = selectedSide === 'over' ? 'under' : 'over';
        if (availableSides.has(fallback)) {
          selectedSide = fallback;
          publishScore = fallback === 'over' ? overScore : underScore;
        } else if (availableSides.size > 0) {
          selectedSide = Array.from(availableSides)[0] as 'over' | 'under';
          publishScore = selectedSide === 'over' ? overScore : underScore;
        }
      }

      if (!isPitcherPropStat(statNorm) && !lineupConfirmed) {
        publishScore = clamp(publishScore - (lineupKnown ? 0.04 : 0.08), 0, 1);
      }

      const selectedSideOdds = getSelectedSideOdds(candidate, selectedSide);
      const selectedSideImpliedProbability = americanOddsToImpliedProbability(selectedSideOdds);
      const hasOnlySelectedSidePriced = availableSides.size === 1 && availableSides.has(selectedSide);

      if (hasOnlySelectedSidePriced && selectedSide === 'under' && !isPitcherPropStat(statNorm)) {
        publishScore = clamp(publishScore - 0.2, 0, 1);
      }

      if (hasOnlySelectedSidePriced && isPitcherPropStat(statNorm) && selectedSideImpliedProbability != null) {
        publishScore = Math.max(
          publishScore,
          clamp((publishScore * 0.4) + (selectedSideImpliedProbability * 0.6), 0, 1),
        );
      }

      if (isLowInformationMlbHitterBinaryUnder(candidate.statType, candidate.marketLineValue, selectedSide)) {
        return finalizeSuppressedMlbCandidate(
          scoredCandidate,
          'low-information binary under',
          publishScore,
          selectedSide,
        );
      }

      if (isLowInformationMlbOneSidedHitterUnder(candidate.statType, candidate.marketLineValue, selectedSide, hasOnlySelectedSidePriced)) {
        return finalizeSuppressedMlbCandidate(
          scoredCandidate,
          'low-information one-sided hitter under',
          publishScore,
          selectedSide,
        );
      }

      if (publishScore < 0.54) {
        return finalizeSuppressedMlbCandidate(
          scoredCandidate,
          'low model confidence',
          publishScore,
          selectedSide,
        );
      }

      if (!isPitcherPropStat(statNorm) && selectedSide === 'over' && oppStarterStrength > 0.66 && oppBullpenFatigue < 0.45) {
        return finalizeSuppressedMlbCandidate(
          scoredCandidate,
          'strong opposing run prevention',
          publishScore,
          selectedSide,
        );
      }

      if ((isPitcherStrikeoutProp(statNorm) || isPitcherOutsProp(statNorm)) && selectedSide === 'over' && oppOffenseStrength > 0.62 && teamBullpenFatigue > 0.58) {
        return finalizeSuppressedMlbCandidate(
          scoredCandidate,
          'pitcher over too context-sensitive',
          publishScore,
          selectedSide,
        );
      }

      scoredCandidate.publishScore = publishScore;
      scoredCandidate.recommendationHint = selectedSide;
      scoredCandidate.prob = scoredCandidate.prob ?? publishScore;
      scoredCandidate.edge = scoredCandidate.edge ?? Math.max(0, publishScore - 0.5);
      return scoredCandidate;
    });
}

export const __mlbPropInternals = {
  normalizeMlbStat,
  getMlbStatVariants,
  isPitcherPropStat,
  scoreMlbCandidatesForPublishing,
  selectMlbCandidatesForPublishing,
  summarizeMlbCandidateFilters,
  validateMlbPropsAgainstCandidates,
  buildMlbFallbackProps,
  enrichMlbPropsWithContext,
  deriveTotalSignal,
  deriveSpreadSignal,
  enrichStructuredSignalNarratives,
  syncForecastProjectionState,
  getRecommendationHintForAvailableSides,
};

function formatMlbCandidateMarkets(candidates: TeamPropCandidate[]): string {
  if (candidates.length === 0) {
    return '\nMLB CANDIDATE MARKETS: None provided. Return an empty props array instead of inventing MLB lines.\n';
  }

  const lines = candidates
    .slice()
    .sort((a, b) => ((b.publishScore ?? b.edge ?? -999) - (a.publishScore ?? a.edge ?? -999)))
    .map((p, idx) => {
      const probPct = p.prob != null ? `${(p.prob * 100).toFixed(1)}%` : 'N/A';
      const edgePct = p.edge != null ? `+${(p.edge * 100).toFixed(1)}%` : 'N/A';
      const publishPct = p.publishScore != null ? `${(p.publishScore * 100).toFixed(1)}%` : 'N/A';
      const oddsStr = p.overOdds != null || p.underOdds != null
        ? ` | overOdds=${p.overOdds ?? 'N/A'} | underOdds=${p.underOdds ?? 'N/A'}`
        : '';
      return `${idx + 1}. ${p.player} | stat=${p.statType} | line=${p.marketLineValue} | suggestedSide=${p.recommendationHint || 'either'} | publishScore=${publishPct} | prob=${probPct} | edge=${edgePct} | source=${p.source}${oddsStr}`;
    });

    return `\nMLB CANDIDATE MARKETS:\n${lines.join('\n')}\nUse ONLY these exact candidate markets for MLB props. Preserve the exact player, stat, line, and over/under direction unless you are explicitly fading the market with an under on the same listed line.\n`;
}

function formatMlbPhasePropContext(result: any, teamSide: 'home' | 'away', teamName: string, opponentName: string): string {
  if (!result?.available || !result.rawData) return '';
  const firstFive = result.rawData.firstFive || {};
  const bullpen = result.rawData.bullpen || {};
  const context = result.rawData.context || {};
  const teamStarter = teamSide === 'home' ? firstFive.homeStarter : firstFive.awayStarter;
  const oppStarter = teamSide === 'home' ? firstFive.awayStarter : firstFive.homeStarter;
  const teamOffense = teamSide === 'home' ? firstFive.homeOffense : firstFive.awayOffense;
  const teamBullpen = teamSide === 'home' ? bullpen.homeBullpen : bullpen.awayBullpen;
  const oppBullpen = teamSide === 'home' ? bullpen.awayBullpen : bullpen.homeBullpen;
  const teamTravel = teamSide === 'home' ? context.travel?.home : context.travel?.away;
  const oppTravel = teamSide === 'home' ? context.travel?.away : context.travel?.home;

  return `
MLB PHASE MODEL FOR ${teamName.toUpperCase()}:
- First 5 innings side score: ${(firstFive.sideScore * 100).toFixed(1)}%
- ${teamName} probable starter: ${teamStarter?.name || 'N/A'}${teamStarter?.fip != null ? ` | FIP ${teamStarter.fip.toFixed(2)} | xFIP ${teamStarter.xfip.toFixed(2)} | WHIP ${teamStarter.whip.toFixed(2)} | K-BB% ${(teamStarter.kBbPct * 100).toFixed(1)}%` : ''}
- Opposing starter: ${oppStarter?.name || 'N/A'}${oppStarter?.fip != null ? ` | FIP ${oppStarter.fip.toFixed(2)} | xFIP ${oppStarter.xfip.toFixed(2)} | WHIP ${oppStarter.whip.toFixed(2)} | K-BB% ${(oppStarter.kBbPct * 100).toFixed(1)}%` : ''}
- ${teamName} offense: full wRC+ ${teamOffense?.fullWrcPlus?.toFixed?.(1) || 'N/A'} | recent wRC+ ${teamOffense?.recentWrcPlus?.toFixed?.(1) || 'N/A'} | projected wRC+ ${teamOffense?.projectedWrcPlus?.toFixed?.(1) || 'N/A'}
- Bullpen phase score: ${(bullpen.sideScore * 100).toFixed(1)}%
- ${teamName} bullpen: ${teamBullpen?.fip != null ? `FIP ${teamBullpen.fip.toFixed(2)} | xFIP ${teamBullpen.xfip.toFixed(2)} | WHIP ${teamBullpen.whip.toFixed(2)} | K% ${(teamBullpen.kPct * 100).toFixed(1)}% | fatigue ${(teamBullpen.workload?.fatigueScore ?? 0.5).toFixed(2)} | last1 pitches ${teamBullpen.workload?.last1DayPitches ?? 'N/A'} | last3 pitches ${teamBullpen.workload?.last3DayPitches ?? 'N/A'}` : 'N/A'}
- ${opponentName} bullpen: ${oppBullpen?.fip != null ? `FIP ${oppBullpen.fip.toFixed(2)} | xFIP ${oppBullpen.xfip.toFixed(2)} | WHIP ${oppBullpen.whip.toFixed(2)} | K% ${(oppBullpen.kPct * 100).toFixed(1)}% | fatigue ${(oppBullpen.workload?.fatigueScore ?? 0.5).toFixed(2)} | last1 pitches ${oppBullpen.workload?.last1DayPitches ?? 'N/A'} | last3 pitches ${oppBullpen.workload?.last3DayPitches ?? 'N/A'}` : 'N/A'}
- Context score: ${(context.sideScore * 100).toFixed(1)}%
- Weather: ${context.weather ? `${context.weather.temperatureF}F, ${context.weather.conditions}, wind ${context.weather.windMph} mph ${context.weather.windDirection}, precip ${context.weather.precipitationChance}%` : 'indoor or unavailable'}
- Travel/rest proxy: ${teamName} last-game hours ${teamTravel?.hoursSinceLastGame ?? 'N/A'}, travel ${teamTravel?.travelMiles ?? 'N/A'} mi | ${opponentName} last-game hours ${oppTravel?.hoursSinceLastGame ?? 'N/A'}, travel ${oppTravel?.travelMiles ?? 'N/A'} mi
- Injuries: team severity ${context.injuries?.[teamSide === 'home' ? 'homeSeverity' : 'awaySeverity'] ?? 'N/A'} vs opponent severity ${context.injuries?.[teamSide === 'home' ? 'awaySeverity' : 'homeSeverity'] ?? 'N/A'}

MLB PROP RULES:
- For hitter props, weigh the opposing starter first, then bullpen quality second.
- For starter pitcher props, weigh first-five context much more than bullpen/context.
- If weather is neutral and bullpens are strong, avoid forcing overs on counting stats.
- If no candidate market supports the angle, pass.
`;
}

function validateMlbPropsAgainstCandidates(props: TeamPropsResult['props'], candidates: TeamPropCandidate[]): TeamPropsResult['props'] {
  if (candidates.length === 0) return [];

  const candidateKeys = new Set<string>();
  const playerLineCounts = new Map<string, number>();
  for (const candidate of candidates) {
    for (const statVariant of getMlbStatVariants(candidate.statType)) {
      candidateKeys.add(`${normalizePropKey(candidate.player)}|${statVariant}|${candidate.marketLineValue.toFixed(1)}`);
    }
    const playerLineKey = `${normalizePropKey(candidate.player)}|${candidate.marketLineValue.toFixed(1)}`;
    playerLineCounts.set(playerLineKey, (playerLineCounts.get(playerLineKey) || 0) + 1);
  }

  return props.filter((p) => {
    const statVariants = getMlbStatVariants(p.stat_type || p.prop || '');
    const line = p.market_line_value ?? extractLineFromPropText(p.prop);
    if (!p.player || line == null) {
      return false;
    }
    const playerKey = normalizePropKey(p.player);
    const lineKey = `${Number(line).toFixed(1)}`;
    for (const statVariant of statVariants) {
      const key = `${playerKey}|${statVariant}|${lineKey}`;
      if (candidateKeys.has(key)) return true;
    }
    return (playerLineCounts.get(`${playerKey}|${lineKey}`) || 0) === 1;
  });
}

function getRecommendationHintForAvailableSides(availableSides: Array<'over' | 'under'>): 'over' | 'under' | null {
  return availableSides.length === 1 ? availableSides[0] : null;
}

function normalizeFallbackStatType(league: string, value: string | null | undefined): string {
  return normalizePlayerPropMarketStat(league, value) || normalizePropKey(String(value || ''));
}

function buildFallbackPropKey(league: string, player: string, statType: string, line: number): string {
  return `${normalizePropKey(player)}|${normalizeFallbackStatType(league, statType)}|${roundToSingleDecimal(line).toFixed(1)}`;
}

function buildSourceBackedCandidateLookupKey(league: string, player: string, statType: string, line: number): string {
  return buildFallbackPropKey(league, player, statType, line);
}

function normalizeSourceBackedRecommendation(value: string | null | undefined): 'over' | 'under' | null {
  const normalized = String(value || '').trim().toLowerCase();
  if (!normalized) return null;
  if (normalized === 'over' || normalized.startsWith('over') || normalized === 'o') return 'over';
  if (normalized === 'under' || normalized.startsWith('under') || normalized === 'u') return 'under';
  if (/\bover\b/.test(normalized)) return 'over';
  if (/\bunder\b/.test(normalized)) return 'under';
  return null;
}

function getPiffTierScore(leg: PiffLeg | null): number {
  if (!leg) return 0;
  const label = String(leg.tier_label || '').toUpperCase();
  if (label === 'T1_LOCK') return 3;
  if (label === 'T2_STRONG') return 2;
  if (label === 'T3_SOLID') return 1;
  const numeric = Number(leg.tier);
  if (numeric === 1) return 3;
  if (numeric === 2) return 2;
  if (numeric === 3) return 1;
  return 0;
}

function buildSourceBackedFallbackStatLabel(league: string, statType: string): string {
  return getPlayerPropLabelForLeague(league, statType)
    || String(statType || 'Prop')
      .replace(/([a-z])([A-Z])/g, '$1 $2')
      .replace(/[_+]+/g, ' ')
      .trim()
      .split(/\s+/)
      .map((word) => word[0]?.toUpperCase() + word.slice(1))
      .join(' ') || 'Prop';
}

function getSourceBackedFallbackDelta(league: string, statType: string): number {
  return getPlayerPropFallbackDeltaForLeague(league, statType) ?? 0.7;
}

function chooseSourceBackedFallbackRecommendation(
  candidate: TeamPropMarketCandidate,
  matchedPiff: PiffLeg | null,
): 'over' | 'under' | null {
  const piffDirection = String(matchedPiff?.direction || '').trim().toLowerCase();
  if ((piffDirection === 'over' || piffDirection === 'under') && candidate.availableSides.includes(piffDirection)) {
    return piffDirection as 'over' | 'under';
  }

  if (candidate.availableSides.includes('over') && candidate.availableSides.includes('under')) {
    const overProb = americanOddsToImpliedProbability(candidate.overOdds);
    const underProb = americanOddsToImpliedProbability(candidate.underOdds);
    if (overProb != null && underProb != null) {
      const diff = Math.abs(overProb - underProb);
      if (diff >= 0.03) {
        return overProb > underProb ? 'over' : 'under';
      }
    }
  }

  return getRecommendationHintForAvailableSides(candidate.availableSides);
}

function isLowInformationSourceBackedFallback(
  league: string,
  statType: string,
  line: number,
  recommendation: 'over' | 'under',
  sidesAvailable: number,
): boolean {
  if (recommendation !== 'under') return false;

  const normalizedLeague = String(league || '').toLowerCase();
  const normalizedStat = normalizeFallbackStatType(league, statType);
  const numericLine = Number(line || 0);

  if (normalizedLeague === 'nba') {
    if (normalizedStat === 'points' && numericLine <= 16.5) return true;
    if (normalizedStat === 'rebounds' && numericLine <= 6.5) return true;
    if (normalizedStat === 'assists' && numericLine <= 5.5) return true;
  }

  if (normalizedLeague === 'ncaab') {
    if (normalizedStat === 'points' && numericLine <= 11.5) return true;
    if (normalizedStat === 'rebounds' && numericLine <= 5.5) return true;
    if (normalizedStat === 'assists' && numericLine <= 3.5) return true;
  }

  if (normalizedLeague === 'nhl' && normalizedStat === 'shots_onGoal' && numericLine <= 2) {
    return true;
  }

  if (sidesAvailable === 1 && numericLine <= 1.5 && (normalizedStat === 'goals' || normalizedStat === 'shots_onTarget')) {
    return true;
  }

  return false;
}

function buildSourceBackedFallbackProjectedValue(
  league: string,
  statType: string,
  line: number,
  recommendation: 'over' | 'under',
  matchedPiff: PiffLeg | null,
): number | null {
  const defaultDelta = getSourceBackedFallbackDelta(league, statType);
  const piffGap = Number(matchedPiff?.gap);
  const delta = Number.isFinite(piffGap) ? Math.max(defaultDelta, Math.abs(piffGap)) : defaultDelta;
  const projected = recommendation === 'over'
    ? line + delta
    : Math.max(0, line - delta);
  return roundToSingleDecimal(projected);
}

function buildSourceBackedFallbackProbability(
  candidate: TeamPropMarketCandidate,
  recommendation: 'over' | 'under',
  matchedPiff: PiffLeg | null,
): number | null {
  const piffProb = normalizePiffProbabilityPct(matchedPiff?.prob);
  if (piffProb != null) return piffProb;

  const selectedOdds = recommendation === 'over'
    ? candidate.overOdds
    : candidate.underOdds;
  const implied = americanOddsToImpliedProbability(selectedOdds);
  if (implied == null) return null;
  const impliedPct = roundToSingleDecimal(implied * 100);

  // Fallback props still need enough spread over market-implied probability
  // to surface as a real signal instead of a null-tier bundle entry.
  const minimumFairEdge = 10.5;
  const floor = recommendation === 'over' ? 66 : 60;
  const lift = candidate.availableSides.length === 2 ? 12 : 10;
  return roundToSingleDecimal(
    Math.min(76, Math.max(floor, impliedPct + lift, impliedPct + minimumFairEdge)),
  );
}

function buildSourceBackedFallbackReasoning(params: {
  league: string;
  player: string;
  statType: string;
  marketLineValue: number;
  recommendation: 'over' | 'under';
  projectedStatValue: number;
  matchedPiff: PiffLeg | null;
}): string {
  const statLabel = buildSourceBackedFallbackStatLabel(params.league, params.statType).toLowerCase();
  const pickCode = params.recommendation === 'over' ? 'O' : 'U';
  const stopDirection = params.recommendation === 'over' ? 'above' : 'below';
  const tierLabel = params.matchedPiff?.tier_label || null;
  const edgePct = params.matchedPiff?.edge != null ? `${Math.round(Number(params.matchedPiff.edge) * 100)}%` : null;

  return [
    `Rain Man projects ${params.player} for ~${params.projectedStatValue} ${statLabel} tonight.`,
    `That supports ${pickCode} only while current markets are at ${params.marketLineValue} (or better).`,
    `Here's how the model got there: this fallback is anchored to an exact source-backed market${tierLabel ? ` with ${tierLabel}` : ' without a validated PIFF match'}${edgePct ? ` and roughly ${edgePct} modeled edge` : ''}.`,
    `The signal fades if current markets move ${stopDirection} ~${params.projectedStatValue}.`,
  ].join(' ');
}

function normalizePiffProbabilityPct(value: number | null | undefined): number | null {
  if (value == null || !Number.isFinite(Number(value))) return null;
  return roundToSingleDecimal(Number(value) * 100);
}

function normalizePropPercentValue(value: number | null | undefined): number | null {
  if (value == null || !Number.isFinite(Number(value))) return null;
  const numeric = Number(value);
  return roundToSingleDecimal(numeric <= 1 ? numeric * 100 : numeric);
}

function buildSourceBackedPiffMap(league: string, teamProps: PiffLeg[]): Map<string, PiffLeg> {
  const piffByKey = new Map<string, PiffLeg>();
  for (const leg of teamProps) {
    const line = Number(leg.line);
    if (!leg.name || !Number.isFinite(line)) continue;
    piffByKey.set(buildFallbackPropKey(league, leg.name, leg.stat, line), leg);
  }
  return piffByKey;
}

function buildMatchedSourceBackedSignal(params: {
  league: string;
  teamName: string;
  teamShort?: string | null;
  candidate: TeamPropMarketCandidate;
  matchedPiff: PiffLeg | null;
  recommendation: 'over' | 'under';
  isHome: boolean;
  existingProp?: TeamPropsResult['props'][number];
}) {
  const projectedStatValue = buildSourceBackedFallbackProjectedValue(
    params.league,
    params.candidate.normalizedStatType,
    params.candidate.marketLineValue,
    params.recommendation,
    params.matchedPiff,
  );
  const prob = buildSourceBackedFallbackProbability(
    params.candidate,
    params.recommendation,
    params.matchedPiff,
  );
  if (projectedStatValue == null || prob == null) return null;

  const edge = normalizePropPercentValue(params.matchedPiff?.edge);
  const selectedOdds = params.recommendation === 'over'
    ? params.candidate.overOdds
    : params.candidate.underOdds;
  const existingContext = params.existingProp?.model_context || {};
  const signal = buildPlayerPropSignal({
    player: params.candidate.player,
    team: params.teamShort || params.teamName,
    teamSide: params.isHome ? 'home' : 'away',
    league: params.league,
    prop: params.existingProp?.prop || `${buildSourceBackedFallbackStatLabel(params.league, params.candidate.normalizedStatType)} ${params.recommendation === 'over' ? 'Over' : 'Under'} ${params.candidate.marketLineValue}`,
    statType: params.candidate.normalizedStatType,
    normalizedStatType: params.candidate.normalizedStatType,
    marketLine: params.candidate.marketLineValue,
    odds: selectedOdds,
    projectedProbability: prob,
    projectedOutcome: projectedStatValue,
    edgePct: edge,
    recommendation: params.recommendation,
    modelContext: {
      ...existingContext,
      tier_label: params.matchedPiff?.tier_label || existingContext.tier_label || null,
      dvp_rank: params.matchedPiff?.dvp_rank ?? existingContext.dvp_rank ?? null,
      dvp_tier: params.matchedPiff?.dvp_tier ?? existingContext.dvp_tier ?? null,
      is_home: existingContext.is_home ?? params.isHome,
      has_modeled_projection: true,
      projection_basis: params.matchedPiff ? 'source_market_piff_exact' : 'source_market_fallback',
      context_summary: existingContext.context_summary || (
        params.matchedPiff
          ? 'Exact source-backed market with matching PIFF support.'
          : 'Fallback generated from an exact source-backed market without a validated PIFF match.'
      ),
    },
    marketSource: params.candidate.source,
    marketCompletenessStatus: params.candidate.completenessStatus ?? null,
    sourceBacked: true,
  });

  return {
    projectedStatValue,
    prob,
    edge,
    selectedOdds,
    signal,
  };
}

export function buildSourceBackedFallbackProps(params: {
  league: string;
  teamName: string;
  candidates: TeamPropMarketCandidate[];
  teamProps: PiffLeg[];
  isHome: boolean;
  limit?: number;
}): TeamPropsResult['props'] {
  const piffByKey = buildSourceBackedPiffMap(params.league, params.teamProps);

  const scored = params.candidates.map((candidate, index) => {
    const marketLineValue = roundToSingleDecimal(Number(candidate.marketLineValue) || 0);
    const matchedPiff = piffByKey.get(buildFallbackPropKey(params.league, candidate.player, candidate.normalizedStatType, marketLineValue)) || null;
    const recommendation = chooseSourceBackedFallbackRecommendation(candidate, matchedPiff);
    if (!recommendation) return null;
    if (isLowInformationSourceBackedFallback(params.league, candidate.normalizedStatType, marketLineValue, recommendation, candidate.availableSides.length)) {
      return null;
    }

    const tierScore = getPiffTierScore(matchedPiff);
    const edgeScore = matchedPiff?.edge != null ? Number(matchedPiff.edge) * 100 : 0;
    const probScore = matchedPiff?.prob != null ? Number(matchedPiff.prob) * 100 : 0;
    const twoWayScore = candidate.availableSides.length === 2 ? 20 : 0;
    const sourceScore = matchedPiff ? 1000 : 0;
    const sortScore = sourceScore + (tierScore * 100) + edgeScore + (probScore * 0.5) + twoWayScore - index;

    return {
      candidate,
      matchedPiff,
      recommendation,
      marketLineValue,
      sortScore,
    };
  }).filter((entry): entry is NonNullable<typeof entry> => entry != null);

  return scored
    .sort((a, b) => b.sortScore - a.sortScore)
    .slice(0, Math.max(1, params.limit ?? 5))
    .flatMap(({ candidate, matchedPiff, recommendation, marketLineValue }) => {
      const matchedSignal = buildMatchedSourceBackedSignal({
        league: params.league,
        teamName: params.teamName,
        candidate,
        matchedPiff,
        recommendation,
        isHome: params.isHome,
      });
      if (!matchedSignal) return [];

      const signal = matchedSignal.signal;
      return {
        player: candidate.player,
        prop: `${buildSourceBackedFallbackStatLabel(params.league, candidate.normalizedStatType)} ${recommendation === 'over' ? 'Over' : 'Under'} ${marketLineValue}`,
        recommendation,
        reasoning: buildSourceBackedFallbackReasoning({
          league: params.league,
          player: candidate.player,
          statType: candidate.normalizedStatType,
          marketLineValue,
          recommendation,
          projectedStatValue: matchedSignal.projectedStatValue,
          matchedPiff,
        }),
        edge: signal?.edgePct ?? matchedSignal.edge ?? undefined,
        prob: signal?.projectedProbability ?? matchedSignal.prob ?? undefined,
        odds: matchedSignal.selectedOdds,
        projected_stat_value: matchedSignal.projectedStatValue,
        stat_type: candidate.normalizedStatType,
        market_line_value: marketLineValue,
        market_source: candidate.source,
        signal_tier: signal?.signalTier ?? null,
        signal_label: signal?.signalLabel ?? null,
        forecast_direction: signal?.forecastDirection ?? recommendation.toUpperCase(),
        projected_probability: signal?.projectedProbability ?? matchedSignal.prob ?? undefined,
        market_implied_probability: signal?.marketImpliedProbability ?? americanOddsToImpliedProbability(matchedSignal.selectedOdds) ?? undefined,
        market_quality_score: signal?.marketQualityScore ?? null,
        market_quality_label: signal?.marketQualityLabel ?? null,
        signal_table_row: signal?.tableRow ?? null,
        model_context: {
          tier_label: matchedPiff?.tier_label || null,
          dvp_rank: matchedPiff?.dvp_rank ?? null,
          dvp_tier: matchedPiff?.dvp_tier ?? null,
          is_home: params.isHome,
          context_summary: matchedPiff
            ? 'Fallback generated from an exact source-backed market with matching PIFF signal.'
            : 'Fallback generated from an exact source-backed market without a validated PIFF match.',
          has_modeled_projection: true,
          projection_basis: matchedPiff ? 'source_market_piff_exact' : 'source_market_fallback',
        },
      };
    });
}

function buildTeamPropIdentityKey(
  league: string,
  prop: Pick<TeamPropsResult['props'][number], 'player' | 'stat_type' | 'market_line_value'>,
): string | null {
  const player = String(prop.player || '').trim();
  const statType = String(prop.stat_type || '').trim();
  const marketLineValue = Number(prop.market_line_value);
  if (!player || !statType || !Number.isFinite(marketLineValue)) return null;
  return buildFallbackPropKey(league, player, statType, marketLineValue);
}

function enrichValidatedSourceBackedProps(params: {
  league: string;
  teamName: string;
  teamShort: string;
  teamProps: PiffLeg[];
  candidates: TeamPropMarketCandidate[];
  props: TeamPropsResult['props'];
  isHome: boolean;
}): TeamPropsResult['props'] {
  const candidateMap = new Map<string, TeamPropMarketCandidate>();
  for (const candidate of params.candidates) {
    candidateMap.set(
      buildSourceBackedCandidateLookupKey(params.league, candidate.player, candidate.normalizedStatType, candidate.marketLineValue),
      candidate,
    );
  }
  const piffByKey = buildSourceBackedPiffMap(params.league, params.teamProps);

  return params.props.flatMap((prop) => {
    const canonicalPlayer = resolveCanonicalName(prop.player, params.league);
    const statType = normalizePlayerPropMarketStat(params.league, prop.stat_type || prop.prop || null);
    const marketLineValue = Number(prop.market_line_value);
    if (!canonicalPlayer || !statType || !Number.isFinite(marketLineValue)) {
      return [];
    }

    const candidate = candidateMap.get(buildSourceBackedCandidateLookupKey(params.league, canonicalPlayer, statType, marketLineValue));
    if (!candidate) return [];

    const recommendation = normalizeSourceBackedRecommendation(prop.recommendation || prop.prop);
    if (!recommendation || !candidate.availableSides.includes(recommendation)) {
      return [];
    }

    const matchedPiff = piffByKey.get(buildFallbackPropKey(params.league, canonicalPlayer, statType, marketLineValue)) || null;
    const matchedSignal = matchedPiff
      ? buildMatchedSourceBackedSignal({
          league: params.league,
          teamName: params.teamName,
          teamShort: params.teamShort,
          candidate,
          matchedPiff,
          recommendation,
          isHome: params.isHome,
          existingProp: prop,
        })
      : null;

    const resolvedProb = normalizePropPercentValue(prop.prob) ?? matchedSignal?.prob ?? null;
    const resolvedProjectedStatValue = Number.isFinite(Number(prop.projected_stat_value))
      ? roundToSingleDecimal(Number(prop.projected_stat_value))
      : matchedSignal?.projectedStatValue ?? null;
    const resolvedOdds = prop.odds ?? matchedSignal?.selectedOdds ?? (recommendation === 'over' ? candidate.overOdds : candidate.underOdds) ?? null;
    const existingContext = prop.model_context || {};
    const signal = buildPlayerPropSignal({
      player: canonicalPlayer,
      team: params.teamShort || params.teamName,
      teamSide: params.isHome ? 'home' : 'away',
      league: params.league,
      prop: prop.prop || candidate.propLabel,
      statType,
      normalizedStatType: statType,
      marketLine: marketLineValue,
      odds: resolvedOdds,
      projectedProbability: resolvedProb,
      projectedOutcome: resolvedProjectedStatValue,
      edgePct: normalizePropPercentValue(prop.edge) ?? matchedSignal?.edge ?? null,
      recommendation,
      modelContext: {
        ...existingContext,
        tier_label: matchedPiff?.tier_label || existingContext.tier_label || null,
        dvp_rank: matchedPiff?.dvp_rank ?? existingContext.dvp_rank ?? null,
        dvp_tier: matchedPiff?.dvp_tier ?? existingContext.dvp_tier ?? null,
        is_home: existingContext.is_home ?? params.isHome,
        has_modeled_projection: resolvedProjectedStatValue != null,
        projection_basis: matchedPiff ? 'source_market_piff_exact' : 'source_market_exact',
      },
      marketSource: candidate.source,
      marketCompletenessStatus: candidate.completenessStatus ?? null,
      sourceBacked: true,
    });

    if (!signal) {
      return [];
    }

    return [{
      ...prop,
      player: canonicalPlayer,
      prop: prop.prop || candidate.propLabel,
      recommendation,
      edge: signal.edgePct,
      prob: signal.projectedProbability,
      projected_stat_value: resolvedProjectedStatValue ?? undefined,
      odds: resolvedOdds ?? undefined,
      stat_type: statType,
      market_line_value: candidate.marketLineValue,
      market_source: candidate.source,
      signal_tier: signal.signalTier,
      signal_label: signal.signalLabel,
      forecast_direction: signal.forecastDirection,
      projected_probability: signal.projectedProbability,
      market_implied_probability: signal.marketImpliedProbability,
      market_quality_score: signal.marketQualityScore,
      market_quality_label: signal.marketQualityLabel,
      signal_table_row: signal.tableRow,
      source_backed: true,
      model_context: {
        ...existingContext,
        tier_label: matchedPiff?.tier_label || existingContext.tier_label || null,
        dvp_rank: matchedPiff?.dvp_rank ?? existingContext.dvp_rank ?? null,
        dvp_tier: matchedPiff?.dvp_tier ?? existingContext.dvp_tier ?? null,
        is_home: existingContext.is_home ?? params.isHome,
        context_summary: existingContext.context_summary
          || (matchedPiff
            ? 'Exact source-backed market retained with matching PIFF support.'
            : 'Exact source-backed market retained after validation.'),
        has_modeled_projection: resolvedProjectedStatValue != null,
        projection_basis: matchedPiff ? 'source_market_piff_exact' : 'source_market_exact',
      },
    }];
  });
}

function topUpSourceBackedProps(params: {
  league: string;
  teamName: string;
  teamProps: TeamPropsResult['props'];
  candidates: TeamPropMarketCandidate[];
  piffTeamProps: PiffLeg[];
  isHome: boolean;
  minimumCount: number;
}): TeamPropsResult['props'] {
  if (!Array.isArray(params.teamProps) || params.teamProps.length >= params.minimumCount) {
    return params.teamProps;
  }

  const existingKeys = new Set(
    params.teamProps
      .map((prop) => buildTeamPropIdentityKey(params.league, prop))
      .filter((key): key is string => Boolean(key)),
  );

  const fallbackProps = buildSourceBackedFallbackProps({
    league: params.league,
    teamName: params.teamName,
    candidates: params.candidates,
    teamProps: params.piffTeamProps,
    isHome: params.isHome,
    limit: Math.max(params.minimumCount * 2, 10),
  });

  const supplemental: TeamPropsResult['props'] = [];
  for (const prop of fallbackProps) {
    if (params.teamProps.length + supplemental.length >= params.minimumCount) break;
    const key = buildTeamPropIdentityKey(params.league, prop);
    if (!key || existingKeys.has(key)) continue;
    existingKeys.add(key);
    supplemental.push(prop);
  }

  if (supplemental.length === 0) {
    return params.teamProps;
  }

  return [...params.teamProps, ...supplemental];
}

function buildSourceBackedFallbackSummary(teamName: string, propCount: number): string {
  return `Rain Man is leaning on ${propCount} source-backed fallback prop${propCount === 1 ? '' : 's'} for ${teamName} after the narrative model failed to return valid market matches.`;
}

function formatMlbFallbackStatLabel(statType: string): string {
  switch (normalizeMlbStat(statType)) {
    case 'pitchingstrikeouts':
      return 'Pitching Strikeouts';
    case 'pitchingearnedruns':
      return 'Pitching Earned Runs';
    case 'pitchingoutsrecorded':
      return 'Pitching Outs Recorded';
    case 'pitchinghitsallowed':
      return 'Pitching Hits Allowed';
    case 'pitchingwalksallowed':
      return 'Pitching Walks Allowed';
    case 'homeruns':
      return 'Home Runs';
    case 'stolenbases':
      return 'Stolen Bases';
    case 'totalbases':
      return 'Total Bases';
    case 'rbis':
      return 'RBIs';
    case 'runs':
      return 'Runs';
    case 'hits':
      return 'Hits';
    case 'strikeouts':
      return 'Strikeouts';
    default:
      return String(statType || 'Prop')
        .replace(/^batting/i, '')
        .replace(/^pitching/i, 'Pitching ')
        .replace(/([a-z])([A-Z])/g, '$1 $2')
        .replace(/[_+]+/g, ' ')
        .trim()
        .split(/\s+/)
        .map((word) => word[0]?.toUpperCase() + word.slice(1))
        .join(' ') || 'Prop';
  }
}

function roundToSingleDecimal(value: number): number {
  return Math.round(value * 10) / 10;
}

function buildMlbFallbackReasoning(
  candidate: TeamPropCandidate,
  recommendation: 'over' | 'under',
): string {
  const statLabel = formatMlbFallbackStatLabel(candidate.statType).toLowerCase();
  const currentLine = roundToSingleDecimal(Number(candidate.marketLineValue) || 0);
  const pickCode = recommendation === 'over' ? 'O' : 'U';
  const supportScore = candidate.publishScore != null ? `${Math.round(candidate.publishScore * 100)}%` : null;

  return [
    `Rain Man is publishing ${candidate.player} ${pickCode} ${currentLine} ${statLabel} as a source-backed MLB fallback.`,
    candidate.reactivatedForFloor
      ? `Here's how the model got there: this shortage fallback is grounded in a real MLB source market that landed just below the normal publish bar${candidate.suppressionReason ? ` (${candidate.suppressionReason})` : ''}${supportScore ? `, with phase support at ${supportScore}` : ''}.`
      : `Here's how the model got there: this fallback is grounded in the strongest publishable MLB source market for this matchup${supportScore ? `, with phase support at ${supportScore}` : ''}.`,
    `Treat ${currentLine} as the actionable threshold; if books move away from that number, the edge likely disappears.`,
  ].join(' ');
}

export function buildMlbFallbackProps(
  candidates: TeamPropCandidate[],
  limit = 5,
): TeamPropsResult['props'] {
  return candidates.slice(0, Math.max(1, limit)).map((candidate) => {
    const recommendation = String(candidate.recommendationHint || 'over').toLowerCase() === 'under' ? 'under' : 'over';
    const marketLineValue = roundToSingleDecimal(Number(candidate.marketLineValue) || 0);
    const prob = candidate.prob != null ? roundToSingleDecimal(candidate.prob * 100) : null;
    const edge = candidate.edge != null ? roundToSingleDecimal(candidate.edge * 100) : null;

    return {
      player: candidate.player,
      prop: `${formatMlbFallbackStatLabel(candidate.statType)} ${recommendation === 'over' ? 'Over' : 'Under'} ${marketLineValue}`,
      recommendation,
      reasoning: buildMlbFallbackReasoning(candidate, recommendation),
      edge: edge ?? undefined,
      prob: prob ?? undefined,
      odds: recommendation === 'over' ? candidate.overOdds : candidate.underOdds,
      stat_type: candidate.statType,
      market_line_value: marketLineValue,
      model_context: {
        context_summary: candidate.reactivatedForFloor
          ? 'Fallback generated from a source-backed MLB candidate lifted in shortage mode to reach the per-team floor.'
          : 'Fallback generated from the strongest publishable MLB source-backed candidate.',
        has_modeled_projection: false,
        projection_basis: 'source_market_fallback',
        phase_support_score: candidate.publishScore != null ? Math.round(candidate.publishScore * 1000) / 1000 : null,
        phase_support_direction: recommendation,
      },
    };
  });
}

function topUpMlbProps(params: {
  teamProps: TeamPropsResult['props'];
  candidates: TeamPropCandidate[];
  minimumCount: number;
}): TeamPropsResult['props'] {
  if (!Array.isArray(params.teamProps) || params.teamProps.length >= params.minimumCount) {
    return params.teamProps;
  }

  const existingKeys = new Set(
    params.teamProps
      .map((prop) => buildTeamPropIdentityKey('mlb', prop))
      .filter((key): key is string => Boolean(key)),
  );

  const fallbackProps = buildMlbFallbackProps(
    params.candidates,
    Math.max(params.minimumCount * 2, 12),
  );

  const supplemental: TeamPropsResult['props'] = [];
  for (const prop of fallbackProps) {
    if (params.teamProps.length + supplemental.length >= params.minimumCount) break;
    const key = buildTeamPropIdentityKey('mlb', prop);
    if (!key || existingKeys.has(key)) continue;
    existingKeys.add(key);
    supplemental.push(prop);
  }

  if (supplemental.length === 0) {
    return params.teamProps;
  }

  return [...params.teamProps, ...supplemental];
}

export async function generateTeamProps(context: {
  teamName: string;
  teamShort: string;
  opponentName: string;
  opponentShort: string;
  league: string;
  isHome: boolean;
  startsAt: string;
  moneyline: { home: number | null; away: number | null };
  spread: any;
  total: any;
  skipTheOddsVerification?: boolean;
  throwOnSourceQueryError?: boolean;
}): Promise<TeamPropsResult> {
  const minSourceBackedPropsPerTeam = 5;
  // Get PIFF props for this team (league-keyed to avoid cross-sport contamination)
  const piffMap = getPiffMap();
  const teamKey = `${context.league}:${context.teamShort.toUpperCase()}`;
  const teamProps = piffMap[teamKey] || [];
  const isMlb = context.league.toLowerCase() === 'mlb';
  const supportedPropLabels = getSupportedPlayerPropLabels(context.league);
  const supportedPropRule = supportedPropLabels.length > 0
    ? `IMPORTANT: For ${String(context.league || '').replace(/_/g, ' ').toUpperCase()}, generate ONLY these supported prop families: ${supportedPropLabels.join(', ')}.`
    : '';

  let mlbDirectCandidates: MlbPropCandidate[] = [];
  let mlbFeedRowCount: number | null = null;
  let mlbOpponentFeedRowCount: number | null = null;
  let mlbOpponentCandidateCount: number | null = null;
  if (isMlb) {
    try {
      mlbFeedRowCount = await countMlbPropFeedRows({
        teamShort: context.teamShort,
        teamName: context.teamName,
        opponentShort: context.opponentShort,
        startsAt: context.startsAt,
      });
      mlbDirectCandidates = await fetchMlbPropCandidates({
        teamShort: context.teamShort,
        teamName: context.teamName,
        opponentShort: context.opponentShort,
        startsAt: context.startsAt,
      });
      mlbOpponentFeedRowCount = await countMlbPropFeedRows({
        teamShort: context.opponentShort,
        teamName: context.opponentName,
        opponentShort: context.teamShort,
        startsAt: context.startsAt,
      });
      const opponentCandidates = await fetchMlbPropCandidates({
        teamShort: context.opponentShort,
        teamName: context.opponentName,
        opponentShort: context.teamShort,
        startsAt: context.startsAt,
      });
      mlbOpponentCandidateCount = opponentCandidates.length;
    } catch (err: any) {
      console.warn(`[team-props] MLB direct candidate load failed: ${err.message}`);
    }
  }

  const hasMlbTeamMismatch =
    isMlb &&
    (mlbFeedRowCount ?? 0) > 0 &&
    (mlbOpponentFeedRowCount ?? 0) > 0 &&
    (
      (mlbDirectCandidates.length === 0 && (mlbOpponentCandidateCount ?? 0) > 0) ||
      (mlbDirectCandidates.length > 0 && (mlbOpponentCandidateCount ?? 0) === 0)
    );

  if (hasMlbTeamMismatch) {
    return getSuppressedTeamProps(context.teamName, 'upstream_team_mismatch', {
      mlb_feed_row_count: mlbFeedRowCount,
      mlb_candidate_count: mlbDirectCandidates.length,
      mlb_publishable_candidate_count: 0,
      mlb_filter_notes: 'Suppressed due to upstream MLB prop feed team mismatch for this game.',
      mlb_suppressed_reason: 'upstream_team_mismatch',
    });
  }

  let piffSection = '';
  if (teamProps.length > 0) {
    const lines = teamProps.map(p => {
      const edgePct = (p.edge * 100).toFixed(1);
      const probPct = (p.prob * 100).toFixed(1);
      const dvpVal = p.dvp_adj ?? p.dvp ?? 0;
      const dvpStr = dvpVal !== 0 ? `, DVP: ${dvpVal > 0 ? '+' : ''}${(dvpVal * 100).toFixed(0)}%` : '';
      return `- ${p.name} O${p.line} ${p.stat} (edge: +${edgePct}%, prob: ${probPct}%${dvpStr})`;
    });
    piffSection = `\nRAIN MAN PROP INTEL FOR ${context.teamName.toUpperCase()}:\n${lines.join('\n')}`;
  }

  let sourceBackedMarketCandidates: TeamPropMarketCandidate[] = [];
  let sourceBackedMarketSection = '';
  if (!isMlb) {
    try {
      sourceBackedMarketCandidates = await fetchTeamPropMarketCandidates({
        league: context.league,
        teamShort: context.teamShort,
        opponentShort: context.opponentShort,
        teamName: context.teamName,
        opponentName: context.opponentName,
        homeTeam: context.isHome ? context.teamName : context.opponentName,
        awayTeam: context.isHome ? context.opponentName : context.teamName,
        startsAt: context.startsAt,
        skipTheOddsVerification: context.skipTheOddsVerification,
        throwOnSourceQueryError: context.throwOnSourceQueryError,
      });
      sourceBackedMarketSection = formatTeamPropMarketCandidatesForPrompt(sourceBackedMarketCandidates, context.teamName);
    } catch (err: any) {
      if (context.throwOnSourceQueryError) {
        throw err;
      }
      console.warn(`[team-props] source-backed market candidate load failed: ${err.message}`);
    }
  }

  if (!isMlb && sourceBackedMarketCandidates.length === 0) {
    return getSuppressedTeamProps(context.teamName, 'no_source_market_candidates', {
      source_market_candidate_count: 0,
      suppressed_reason: 'no_source_market_candidates',
    });
  }

  let mlbPhaseSection = '';
  let mlbCandidateSection = '';
  let mlbFilterSection = '';
  let mlbPhaseResult: any = null;
  const mlbCandidates: TeamPropCandidate[] = isMlb ? [
    ...mlbDirectCandidates.map((p) => ({
      player: p.player,
      statType: p.statType,
      marketLineValue: p.marketLineValue,
      recommendationHint: getRecommendationHintForAvailableSides(p.availableSides),
      edge: null,
      prob: null,
      source: 'player_prop_line' as const,
      propLabel: p.prop,
      overOdds: p.overOdds,
      underOdds: p.underOdds,
    })),
    ...teamProps
      .filter((p) => !mlbDirectCandidates.some((m) =>
        normalizePropKey(m.player) === normalizePropKey(p.name) &&
        normalizeMlbStat(m.statType) === normalizeMlbStat(p.stat) &&
        Number(m.marketLineValue).toFixed(1) === Number(p.line).toFixed(1)
      ))
      .map((p) => ({
        player: p.name,
        statType: p.stat,
        marketLineValue: p.line,
        recommendationHint: p.direction || null,
        edge: p.edge,
        prob: p.prob,
        source: 'piff' as const,
        propLabel: `${p.stat} ${p.line}`,
      })),
  ] : [];
  const initialMlbCandidateCount = mlbCandidates.length;

  if (isMlb) {
    try {
      const phase = await mlbPhaseSignal.collect({
        league: 'mlb',
        homeTeam: context.isHome ? context.teamName : context.opponentName,
        awayTeam: context.isHome ? context.opponentName : context.teamName,
        homeShort: context.isHome ? context.teamShort : context.opponentShort,
        awayShort: context.isHome ? context.opponentShort : context.teamShort,
        startsAt: context.startsAt,
        eventId: 'team-props',
      });
      mlbPhaseResult = phase;
      mlbPhaseSection = formatMlbPhasePropContext(phase, context.isHome ? 'home' : 'away', context.teamName, context.opponentName);
      const scoredCandidates = scoreMlbCandidatesForPublishing(
        mlbCandidates.map((candidate) => ({ ...candidate })),
        phase,
        context.isHome ? 'home' : 'away',
      );
      mlbFilterSection = summarizeMlbCandidateFilters(scoredCandidates);
      mlbCandidates.length = 0;
      mlbCandidates.push(
        ...selectMlbCandidatesForPublishing(scoredCandidates, minSourceBackedPropsPerTeam)
      );
      if (mlbCandidates.length === 0 && initialMlbCandidateCount > 0) {
        return getSuppressedTeamProps(context.teamName, 'no_meaningful_mlb_candidates', {
          mlb_feed_row_count: mlbFeedRowCount,
          mlb_candidate_count: initialMlbCandidateCount,
          mlb_publishable_candidate_count: 0,
          mlb_filter_notes: mlbFilterSection.trim() || null,
          mlb_suppressed_reason: 'no_meaningful_mlb_candidates',
        });
      }
    } catch (err: any) {
      console.warn(`[team-props] MLB phase context failed: ${err.message}`);
    }
      mlbCandidateSection = formatMlbCandidateMarkets(mlbCandidates);
  }

  // Inject ESPN roster so LLM uses current team composition
  const rosterSection = formatRosterForPrompt(context.teamShort, context.teamName, context.league);

  const prompt = `Generate a detailed player props forecast for ${context.teamName} (${context.teamShort}) in their ${context.league.toUpperCase()} game ${context.isHome ? 'hosting' : 'visiting'} ${context.opponentName}.

MATCHUP: ${context.isHome ? `${context.opponentName} @ ${context.teamName}` : `${context.teamName} @ ${context.opponentName}`}
GAME TIME: ${context.startsAt}
LEAGUE: ${context.league.toUpperCase()}

${rosterSection ? rosterSection + '\n' : ''}
CRITICAL ROSTER RULE: ONLY generate props for players listed in the roster above. These are the CURRENT ${context.teamName} players per ESPN. Players who have been traded away are NOT on this team — do NOT include them even if you remember them being on this team. If the roster is empty, use your best knowledge but prefer recent information.

ODDS:
- Moneyline: Home ${context.moneyline.home ?? 'N/A'} | Away ${context.moneyline.away ?? 'N/A'}
- Spread: Home ${context.spread?.home?.line ?? 'N/A'} | Away ${context.spread?.away?.line ?? 'N/A'}
- Total: ${context.total?.over?.line ?? 'N/A'}
${piffSection}
${sourceBackedMarketSection}
${mlbPhaseSection}
${mlbFilterSection}
${mlbCandidateSection}

Return ONLY this JSON structure with 5-8 player prop projections for ${context.teamName} players:
{
  "team": "${context.teamName}",
  "summary": "1-2 sentence overview of the prop outlook for this team",
  "props": [
    {
      "player": "Player Full Name",
      "prop": "Stat Type + Line (e.g. Points Over 25.5)",
      "recommendation": "over or under",
      "reasoning": "Must start with 'Rain Man projects [PLAYER] for ~[X] [STAT] tonight.' then 2-3 sentence analysis",
      "edge": 5.0,
      "prob": 65.0,
      "projected_stat_value": 26.5,
      "stat_type": "points",
      "market_line_value": 25.5,
      "model_context": {
        "tier_label": "T2_STRONG",
        "season_average": 24.8,
        "last5_average": 26.4,
        "season_hit_rate": 0.74,
        "last5_hit_rate": 0.8,
        "projected_minutes": 35,
        "is_home": ${context.isHome ? 'true' : 'false'},
        "is_b2b": false,
        "dvp_tier": "EASY",
        "dvp_rank": 24,
        "injury_context": "Usage boost if key teammate is out; otherwise neutral.",
        "volatility": 0.34,
        "context_summary": "Home spot, stable minutes, favorable matchup, no major rest concern."
      }
    }
  ]
}

Focus on the most actionable props with the best edges.

CRITICAL MARKET RULE:
When a SOURCE-BACKED PLAYER PROP MARKETS section is present, ONLY generate props for those exact player/stat/line combinations. Do not invent alternate lines, combo markets, or players outside that list.
Prefer mainstream markets with both over and under prices available. Treat any market showing one side as N/A as secondary context, and avoid low-line under-only props unless a real restriction or injury context is explicitly driving the call.
Prioritize established starters and stable-minute rotation players over fringe bench pieces. Avoid filler unders on low-volume role players when a cleaner starter market exists.

When available, populate model_context with the actual factors driving the pick: tier, season/L5 averages, hit rates, projected minutes, home/away, back-to-back status, DVP, injury context, and volatility. Use null when a field is not available instead of inventing a value.
${supportedPropRule}`;

  const systemPrompt = `You are Rain Man, the authoritative voice behind Rainmaker Sports, specializing in player props. You combine prop intelligence data, matchup analysis, and statistical trends to produce precise player prop forecasts. You ALWAYS return valid JSON and nothing else. Never reference internal model names.

GOLDEN RULE — QUANTIFY FIRST:
Each prop's "reasoning" MUST open with: "Rain Man projects [PLAYER] for ~[X] [STAT] tonight."
Second line: "That supports [O/U] only while current markets are at [LINE] (or better)."
Third line: "Here's how the model got there:"
Then continue with 2-3 sentences of analysis.

STOP-POINT RULE:
Include in reasoning: "The signal fades if current markets move above/below ~[PROJECTED_STAT]."

LANGUAGE RULE: Use "current markets" not "betting lines", "market interest" not "bettors".
NAMING RULE: Use "Rain Man" only ONCE per prop reasoning block. After that, use "the model", "the signal", "RM", or "the forecast".
EDITORIAL RULE: Never use "lock", "guarantee", "sure thing", "free money". End with observational language. Frame props as signals, not recommendations.`;

  const buildTeamPropsFailureFallback = async () => {
      if (isMlb) {
      if (mlbCandidates.length > 0) {
        const fallbackProps = await enrichMlbPropsWithContext(buildMlbFallbackProps(mlbCandidates, minSourceBackedPropsPerTeam), mlbCandidates, mlbPhaseResult, {
          teamShort: context.teamShort,
          opponentShort: context.opponentShort,
          homeShort: context.isHome ? context.teamShort : context.opponentShort,
          teamSide: context.isHome ? 'home' : 'away',
        });
        return {
          team: context.teamName,
          summary: `Rain Man isolated ${fallbackProps.length} publishable MLB prop candidates for ${context.teamName}; these are the strongest source-backed signals right now.`,
          props: fallbackProps,
          metadata: {
            mlb_feed_row_count: mlbFeedRowCount,
            mlb_candidate_count: initialMlbCandidateCount,
            mlb_publishable_candidate_count: mlbCandidates.length,
            mlb_filter_notes: mlbFilterSection.trim() || null,
            fallback_reason: 'llm_parse_failure',
          },
        } as TeamPropsResult;
      }
      return getDefaultTeamProps(context.teamName);
    }

    if (sourceBackedMarketCandidates.length > 0) {
      const fallbackProps = buildSourceBackedFallbackProps({
        league: context.league,
        teamName: context.teamName,
        candidates: sourceBackedMarketCandidates,
        teamProps,
        isHome: context.isHome,
        limit: minSourceBackedPropsPerTeam,
      });
      if (fallbackProps.length > 0) {
        return {
          team: context.teamName,
          summary: buildSourceBackedFallbackSummary(context.teamName, fallbackProps.length),
          props: fallbackProps,
          metadata: {
            source_market_candidate_count: sourceBackedMarketCandidates.length,
            fallback_reason: 'llm_parse_failure',
          },
        } as TeamPropsResult;
      }
    }

    return getDefaultTeamProps(context.teamName);
  };

  for (let attempt = 0; attempt < 2; attempt++) {
    try {
      const content = await callLLM(systemPrompt, prompt, { maxTokens: 4500 }, {
        category: 'team_props', league: context.league,
      });
      const parsed = JSON.parse(content) as TeamPropsResult;
      if (!parsed.props || !Array.isArray(parsed.props)) {
        throw new Error('Missing props array in team props response');
      }
      if (isMlb) {
        parsed.metadata = {
          ...(parsed.metadata || {}),
          mlb_feed_row_count: mlbFeedRowCount,
          mlb_candidate_count: initialMlbCandidateCount,
          mlb_publishable_candidate_count: mlbCandidates.length,
          mlb_filter_notes: mlbFilterSection.trim() || null,
        };
      }
      if (isMlb) {
        parsed.props = validateMlbPropsAgainstCandidates(parsed.props, mlbCandidates);
        if (parsed.props.length === 0 && mlbCandidates.length > 0) {
          console.warn(`[team-props] MLB fallback activated for ${context.teamName}: model returned no valid props despite ${mlbCandidates.length} publishable candidates`);
          parsed.props = buildMlbFallbackProps(mlbCandidates, minSourceBackedPropsPerTeam);
          if (!String(parsed.summary || '').trim()) {
            parsed.summary = `Rain Man isolated ${mlbCandidates.length} publishable MLB prop candidates for ${context.teamName}; these are the strongest source-backed signals right now.`;
          }
        } else if (parsed.props.length > 0 && parsed.props.length < minSourceBackedPropsPerTeam) {
          const toppedUp = topUpMlbProps({
            teamProps: parsed.props,
            candidates: mlbCandidates,
            minimumCount: minSourceBackedPropsPerTeam,
          });
          if (toppedUp.length > parsed.props.length) {
            console.log(
              `[team-props] MLB top-up: added ${toppedUp.length - parsed.props.length} fallback props (${toppedUp.length} total) for ${context.teamName}`,
            );
            parsed.props = toppedUp;
          }
        }
        parsed.props = await enrichMlbPropsWithContext(parsed.props, mlbCandidates, mlbPhaseResult, {
          teamShort: context.teamShort,
          opponentShort: context.opponentShort,
          homeShort: context.isHome ? context.teamShort : context.opponentShort,
          teamSide: context.isHome ? 'home' : 'away',
        });
      } else if (sourceBackedMarketCandidates.length > 0) {
        const beforeValidationCount = parsed.props.length;
        parsed.props = validateTeamPropsAgainstMarketCandidates(parsed.props, sourceBackedMarketCandidates, context.league);
        if (parsed.props.length < beforeValidationCount) {
          console.log(
            `[team-props] Source-backed validation: ${beforeValidationCount - parsed.props.length} props removed (${parsed.props.length} remaining) for ${context.teamName}`,
          );
        }
        parsed.props = enrichValidatedSourceBackedProps({
          league: context.league,
          teamName: context.teamName,
          teamShort: context.teamShort,
          teamProps,
          candidates: sourceBackedMarketCandidates,
          props: parsed.props,
          isHome: context.isHome,
        });
        if (parsed.props.length === 0) {
          const fallbackProps = buildSourceBackedFallbackProps({
            league: context.league,
            teamName: context.teamName,
            candidates: sourceBackedMarketCandidates,
            teamProps,
            isHome: context.isHome,
            limit: minSourceBackedPropsPerTeam,
          });
          if (fallbackProps.length > 0) {
            console.warn(
              `[team-props] Source-backed fallback activated for ${context.teamName}: model returned no valid props despite ${sourceBackedMarketCandidates.length} candidate markets`,
            );
            parsed.props = fallbackProps;
            parsed.summary = buildSourceBackedFallbackSummary(context.teamName, fallbackProps.length);
          } else {
            return getSuppressedTeamProps(context.teamName, 'no_valid_source_market_matches', {
              source_market_candidate_count: sourceBackedMarketCandidates.length,
              suppressed_reason: 'no_valid_source_market_matches',
            });
          }
        } else {
          const toppedUp = topUpSourceBackedProps({
            league: context.league,
            teamName: context.teamName,
            teamProps: parsed.props,
            candidates: sourceBackedMarketCandidates,
            piffTeamProps: teamProps,
            isHome: context.isHome,
            minimumCount: minSourceBackedPropsPerTeam,
          });
          if (toppedUp.length > parsed.props.length) {
            console.log(
              `[team-props] Source-backed top-up: added ${toppedUp.length - parsed.props.length} fallback props (${toppedUp.length} total) for ${context.teamName}`,
            );
            parsed.props = toppedUp;
          }
        }
      }
      // Validate props: filter out players not on the team per ESPN roster
      const originalCount = parsed.props.length;
      parsed.props = parsed.props.filter((p, i) => {
        const allowsMissingProjection = p?.model_context?.projection_basis === 'source_market_fallback';
        if (p.projected_stat_value == null && !allowsMissingProjection) {
          console.warn(`[team-props] prop ${i} (${p.player}) missing projected_stat_value`);
        }
        if (!isPlayerOnTeam(p.player, context.teamShort, context.league)) {
          console.warn(`[team-props] ROSTER FILTER: Removed ${p.player} — not on ${context.teamShort} per ESPN roster`);
          return false;
        }
        return true;
      });
      if (parsed.props.length < originalCount) {
        console.log(`[team-props] Roster validation: ${originalCount - parsed.props.length} props removed (${parsed.props.length} remaining) for ${context.teamName}`);
      }
      return parsed;
    } catch (err) {
      console.error(`[team-props] attempt ${attempt + 1} failed:`, err);
      if (attempt < 1) {
        await new Promise(r => setTimeout(r, 2000));
        continue;
      }
      return await buildTeamPropsFailureFallback();
    }
  }

  return await buildTeamPropsFailureFallback();
}

// ============================================================
// Steam & Sharp Insight Generation
// ============================================================

export interface SteamInsightResult {
  title: string;
  education: string;
  observation: string;
  supporting_data: Array<{ market: string; move: string; velocity: string; source?: string; bookmaker?: string }>;
  why_it_matters: string;
  confidence_level: string;
}

export interface SharpInsightResult {
  title: string;
  education: string;
  direction: string;
  supporting_data: Array<{ market: string; detail: string; significance: string }>;
  market_analysis: string;
  confidence_assessment: string;
}

export async function generateSteamInsight(context: {
  homeTeam: string;
  awayTeam: string;
  league: string;
  forecastSummary: string;
  sharpMoves: any[];
  lineMovements: any[];
}): Promise<SteamInsightResult> {
  const steamMoves = context.sharpMoves.filter((m: any) => m.isSteamMove);
  const steamLines = context.lineMovements.filter((m: any) => m.steamMove);

  const prompt = `Analyze the steam move signals for this ${context.league.toUpperCase()} game: ${context.awayTeam} @ ${context.homeTeam}.

EXISTING FORECAST SUMMARY:
${context.forecastSummary}

STEAM MOVES DETECTED (from SharpMove table, isSteamMove=true):
${steamMoves.length > 0 ? JSON.stringify(steamMoves, null, 2) : 'No direct steam moves detected.'}

LINE MOVEMENTS WITH STEAM FLAG (from LineMovement table, steamMove=true):
${steamLines.length > 0 ? JSON.stringify(steamLines, null, 2) : 'No steam-flagged line movements.'}

ALL SHARP MOVES (for broader context):
${context.sharpMoves.length > 0 ? JSON.stringify(context.sharpMoves.slice(0, 10), null, 2) : 'None available.'}

Return ONLY this JSON:
{
  "title": "Steam Move Alert: [brief title]",
  "education": "1-2 sentence explanation of what steam moves are and why they matter for market speculators",
  "observation": "2-3 sentence analysis of what the steam signals indicate for this game",
  "supporting_data": [
    { "market": "spread/total/moneyline", "move": "market change description", "velocity": "speed of move", "source": "pricing source or 'multiple'" }
  ],
  "why_it_matters": "2-3 sentences on the practical market implication",
  "confidence_level": "HIGH/MEDIUM/LOW based on signal strength"
}`;

  const systemPrompt = 'You are Rain Man, the authoritative voice behind Rainmaker Sports, specializing in steam move detection and market movement analysis. You explain complex signals in clear, actionable language. Return valid JSON only. Never reference internal model names. LANGUAGE RULE: Use "market speculators" not "bettors", "market venues" not "sportsbooks", "market movement" not "line movement", "market price" not "odds". NAMING RULE: Use "Rain Man" only ONCE — then rotate: RM, the model, the signal, the analysis. EDITORIAL RULE: Never use "lock", "guarantee", "sure thing", "free money". End with observational language, not forceful instruction.';

  for (let attempt = 0; attempt < 2; attempt++) {
    try {
      const content = await callLLM(systemPrompt, prompt, { maxTokens: 3000 }, {
        category: 'insight', subcategory: 'steam', league: context.league,
      });
      const parsed = JSON.parse(content) as SteamInsightResult;
      if (!parsed.title || !parsed.observation) {
        throw new Error('Missing required steam insight fields');
      }
      // ── NARRATIVE ENGINE: Apply editorial guardrails ──
      const { editorialGuardrails: guardrails } = require('./narrative-engine');
      parsed.observation = guardrails(parsed.observation);
      parsed.why_it_matters = guardrails(parsed.why_it_matters);
      return parsed;
    } catch (err) {
      console.error(`[steam-insight] attempt ${attempt + 1} failed:`, err);
      if (attempt < 1) {
        await new Promise(r => setTimeout(r, 2000));
        continue;
      }
      return getDefaultSteamInsight(context);
    }
  }

  return getDefaultSteamInsight(context);
}

export async function generateSharpInsight(context: {
  homeTeam: string;
  awayTeam: string;
  league: string;
  forecastSummary: string;
  sharpMoneyIndicator: string;
  sharpMoves: any[];
  lineMovements: any[];
}): Promise<SharpInsightResult> {
  const prompt = `Analyze the sharp money signals for this ${context.league.toUpperCase()} game: ${context.awayTeam} @ ${context.homeTeam}.

EXISTING FORECAST SUMMARY:
${context.forecastSummary}

SHARP MONEY INDICATOR (from AI model):
${context.sharpMoneyIndicator || 'Not available'}

SHARP MOVES (from SharpMove table):
${context.sharpMoves.length > 0 ? JSON.stringify(context.sharpMoves.slice(0, 10), null, 2) : 'None available.'}

LINE MOVEMENTS (from LineMovement table):
${context.lineMovements.length > 0 ? JSON.stringify(context.lineMovements.slice(0, 10), null, 2) : 'None available.'}

Return ONLY this JSON:
{
  "title": "Sharp Money Analysis: [brief title]",
  "education": "1-2 sentence explanation of what sharp money is and why tracking it matters",
  "direction": "2-3 sentence summary of which side sharp money favors and why",
  "supporting_data": [
    { "market": "spread/total/moneyline", "detail": "what the data shows", "significance": "HIGH/MEDIUM/LOW" }
  ],
  "market_analysis": "2-3 sentences analyzing market reactions and pricing adjustments",
  "confidence_assessment": "1-2 sentences on how confident we are in this sharp signal"
}`;

  const systemPrompt = 'You are Rain Man, the authoritative voice behind Rainmaker Sports, specializing in sharp money flow analysis and professional market signals. You explain complex signals in clear, actionable language. Return valid JSON only. Never reference internal model names. LANGUAGE RULE: Use "market speculators" not "bettors", "market venues" not "sportsbooks", "market movement" not "line movement", "market price" not "odds". NAMING RULE: Use "Rain Man" only ONCE — then rotate: RM, the model, the signal, the analysis. EDITORIAL RULE: Never use "lock", "guarantee", "sure thing", "free money". End with observational language, not forceful instruction.';

  for (let attempt = 0; attempt < 2; attempt++) {
    try {
      const content = await callLLM(systemPrompt, prompt, { maxTokens: 3000 }, {
        category: 'insight', subcategory: 'sharp', league: context.league,
      });
      const parsed = JSON.parse(content) as SharpInsightResult;
      if (!parsed.title || !parsed.direction) {
        throw new Error('Missing required sharp insight fields');
      }
      // ── NARRATIVE ENGINE: Apply editorial guardrails ──
      const { editorialGuardrails: guardrails } = require('./narrative-engine');
      parsed.direction = guardrails(parsed.direction);
      parsed.market_analysis = guardrails(parsed.market_analysis);
      parsed.confidence_assessment = guardrails(parsed.confidence_assessment);
      return parsed;
    } catch (err) {
      console.error(`[sharp-insight] attempt ${attempt + 1} failed:`, err);
      if (attempt < 1) {
        await new Promise(r => setTimeout(r, 2000));
        continue;
      }
      return getDefaultSharpInsight(context);
    }
  }

  return getDefaultSharpInsight(context);
}

function getDefaultSteamInsight(ctx: any): SteamInsightResult {
  return {
    title: `Steam Move Alert: ${ctx.awayTeam} @ ${ctx.homeTeam}`,
    education: 'Steam moves occur when sharp market speculators simultaneously place large positions at multiple market venues, causing rapid pricing shifts across the market.',
    observation: 'Steam signal analysis is being generated. Check back shortly for detailed insights.',
    supporting_data: [],
    why_it_matters: 'Steam moves often indicate professional syndicates have identified an edge in the market.',
    confidence_level: 'MEDIUM',
  };
}

function getDefaultSharpInsight(ctx: any): SharpInsightResult {
  return {
    title: `Sharp Money Analysis: ${ctx.awayTeam} @ ${ctx.homeTeam}`,
    education: 'Sharp money refers to positions taken by professional market speculators and syndicates who consistently beat the closing market price.',
    direction: 'Sharp money analysis is being generated. Check back shortly for detailed insights.',
    supporting_data: [],
    market_analysis: 'Market pricing adjustments are being analyzed.',
    confidence_assessment: 'Analysis pending.',
  };
}

function getDefaultTeamProps(teamName: string): TeamPropsResult {
  return {
    team: teamName,
    summary: `Player props analysis for ${teamName} is being generated. Check back shortly.`,
    props: [],
  };
}

function getSuppressedTeamProps(teamName: string, reason: string, metadata: TeamPropsResult['metadata']): TeamPropsResult {
  const isMlbReason = reason.includes('mlb') || reason.includes('upstream_team_mismatch');
  return {
    team: teamName,
    summary: isMlbReason
      ? `Props suppressed for ${teamName} due to ${reason.replace(/_/g, ' ')} in the MLB feed.`
      : `Props suppressed for ${teamName} due to ${reason.replace(/_/g, ' ')} in the source market feed.`,
    props: [],
    metadata,
  };
}

function getDefaultForecast(ctx: any): ForecastResult {
  return {
    summary: `${ctx.awayTeam} at ${ctx.homeTeam} — Analysis is being generated. Check back shortly.`,
    winner_pick: ctx.homeTeam,
    confidence: 0.5,
    spread_analysis: 'Spread analysis pending deeper data review.',
    total_analysis: 'Total analysis pending.',
    key_factors: ['Home court advantage', 'Recent form', 'Head-to-head record'],
    sharp_money_indicator: 'No clear sharp money signal detected.',
    line_movement_analysis: 'Lines have remained stable.',
    prop_highlights: [],
    historical_trend: 'Historical data being compiled.',
    value_rating: 5,
    projected_lines: {
      moneyline: { home: -110, away: -110 },
      spread: { home: -1.5, away: 1.5 },
      total: 210,
    },
    projected_margin: -1.5,
    projected_total_points: 210,
    forecast_side: ctx.homeTeam,
    spread_edge: 0,
    total_direction: 'NONE',
    total_edge: 0,
    projected_winner: ctx.homeTeam,
  };
}