Tier 5A execution layer + Alpha Release tab + edge strip fix

- analytics/execution_layer.py: New post-model enrichment pass (5 sequential
tasks: market disagreement, edge quality, timing, correlation, final score)
- analytics/props_mapper.py: Wire enrich_with_execution_layer at end of
map_hr_props_to_model; try/except with logger.warning fallback
- analytics/recommendation_engine.py: Add prop_odds_df param; inject real live
HR prop odds per batter (MAX odds_american, normalized + raw name fallback,
book_hr_odds_source field); logs mapping misses
- data/live_prop_odds.py: Fix silent exception in fetch_live_prop_odds
- app.py: load_hr_prop_odds_for_game (60s TTL) wired into dashboard; replace
render_algorithm_breakdown with render_alpha_release (10 expanders, disclaimer,
no WBC content); rename nav entry
- visualization/props_page.py: Store mapped df in session_state; Execution Layer
expander after HR props table
- visualization/debug_page.py: Section 5c Execution Layer reading from
session_state
- visualization/recommendation_panels.py: BOOK column shows ~odds with tooltip
when book_hr_odds_source == placeholder

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

analytics/execution_layer.py

@@ -0,0 +1,356 @@
+"""
+analytics/execution_layer.py
+
+Tier 5A — Execution Layer (Alpha Release)
+
+Post-model enrichment pass operating exclusively on already-computed outputs
+(model probs + book odds). No simulation logic, no probability calculations,
+no model changes.
+
+Entry point: enrich_with_execution_layer(df) → df with execution fields added.
+"""
+
+from __future__ import annotations
+
+import statistics
+from typing import Any
+
+import pandas as pd
+
+from analytics.no_vig_props import american_to_implied_prob
+
+# ---------------------------------------------------------------------------
+# Thresholds
+# ---------------------------------------------------------------------------
+OUTLIER_THRESHOLD = 0.03   # 3pp deviation from median → outlier
+STALE_THRESHOLD = 0.025    # 2.5pp worse than median → stale book
+AGGRESSIVE_THRESHOLD = 0.02  # 2pp better than median → aggressive/timing flag
+
+_TIMESTAMP_KEYS = ("last_update", "timestamp", "odds_timestamp", "updated_at")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _safe_float(val: Any, default: float | None = None) -> float | None:
+    if val is None:
+        return default
+    try:
+        return float(val)
+    except (TypeError, ValueError):
+        return default
+
+
+def _safe_implied(odds: Any) -> float | None:
+    if odds is None:
+        return None
+    try:
+        return american_to_implied_prob(odds)
+    except Exception:
+        return None
+
+
+def _make_player_game_key(row: pd.Series) -> str:
+    event_id = str(row.get("event_id") or "").strip()
+    player_name = str(row.get("player_name") or "").strip()
+    if event_id and event_id not in ("nan", "None", ""):
+        return f"{event_id}|{player_name}"
+    away = str(row.get("away_team") or "").strip()
+    home = str(row.get("home_team") or "").strip()
+    return f"{away}|{home}|{player_name}"
+
+
+def _make_game_key(row: pd.Series) -> str:
+    event_id = str(row.get("event_id") or "").strip()
+    if event_id and event_id not in ("nan", "None", ""):
+        return event_id
+    away = str(row.get("away_team") or "").strip()
+    home = str(row.get("home_team") or "").strip()
+    return f"{away}_{home}"
+
+
+# ---------------------------------------------------------------------------
+# Task 1 — Market Disagreement
+# ---------------------------------------------------------------------------
+
+def _compute_market_fields(df: pd.DataFrame) -> pd.DataFrame:
+    """Add best_price, median_price, market_width, market_outlier_flag, stale_book_flag."""
+    df = df.copy()
+
+    # Build scoped player-game keys
+    keys = df.apply(_make_player_game_key, axis=1)
+    df["_pg_key"] = keys
+
+    # Pre-compute implied probs for each row
+    df["_implied"] = df["odds_american"].apply(_safe_implied)
+
+    # Group stats per scoped player-game key
+    group_stats: dict[str, dict] = {}
+    for key, grp in df.groupby("_pg_key"):
+        implied_vals = [v for v in grp["_implied"].tolist() if v is not None]
+        if not implied_vals:
+            group_stats[key] = {
+                "best": None, "worst": None, "median": None, "width": None
+            }
+            continue
+        best = min(implied_vals)   # lowest implied = best for bettor
+        worst = max(implied_vals)
+        med = statistics.median(implied_vals)
+        width = abs(worst - best)
+        group_stats[key] = {"best": best, "worst": worst, "median": med, "width": width}
+
+    best_prices: list[float | None] = []
+    median_prices: list[float | None] = []
+    market_widths: list[float | None] = []
+    outlier_flags: list[bool] = []
+    stale_flags: list[bool] = []
+
+    for _, row in df.iterrows():
+        key = row["_pg_key"]
+        stats = group_stats.get(key, {})
+        this_implied = row["_implied"]
+
+        best_prices.append(stats.get("best"))
+        median_prices.append(stats.get("median"))
+        market_widths.append(stats.get("width"))
+
+        med = stats.get("median")
+        if this_implied is not None and med is not None:
+            outlier_flags.append(abs(this_implied - med) > OUTLIER_THRESHOLD)
+            stale_flags.append((this_implied - med) > STALE_THRESHOLD)
+        else:
+            outlier_flags.append(False)
+            stale_flags.append(False)
+
+    df["best_price"] = best_prices
+    df["median_price"] = median_prices
+    df["market_width"] = market_widths
+    df["market_outlier_flag"] = outlier_flags
+    df["stale_book_flag"] = stale_flags
+
+    df.drop(columns=["_pg_key", "_implied"], inplace=True)
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Task 2 — Edge Quality Filters
+# ---------------------------------------------------------------------------
+
+def _compute_edge_quality(df: pd.DataFrame) -> pd.DataFrame:
+    """Add confidence_score, volatility_score, signal_strength_score,
+    edge_raw, edge_filtered, edge_filter_flags."""
+    df = df.copy()
+
+    conf_scores: list[float] = []
+    vol_scores: list[float] = []
+    sig_scores: list[float] = []
+    edge_raws: list[float | None] = []
+    edge_filtered_vals: list[float | None] = []
+    edge_flag_strs: list[str] = []
+
+    for _, row in df.iterrows():
+        source = str(row.get("model_hr_prob_source") or "unavailable")
+        context_applied = bool(row.get("pregame_context_applied") or False)
+        edge_raw = _safe_float(row.get("edge"))
+        market_width = _safe_float(row.get("market_width"), default=0.0)
+
+        # Context adj magnitude
+        pitcher_adj = _safe_float(row.get("pregame_pitcher_context_adj"), default=0.0)
+        park_adj = _safe_float(row.get("pregame_park_context_adj"), default=0.0)
+        context_mag = abs(pitcher_adj or 0.0) + abs(park_adj or 0.0)
+
+        # Confidence score
+        if source == "internal_model_baseline":
+            conf = 1.0 if context_applied else 0.7
+        else:
+            conf = 0.3
+
+        # Volatility score (weighted blend, range [0, 1])
+        width_component = min(1.0, (market_width or 0.0) / 0.10)
+        ctx_component = min(1.0, context_mag / 0.02) if context_mag > 0 else 0.0
+        vol = 0.7 * width_component + 0.3 * ctx_component
+
+        # Signal strength score
+        if source == "internal_model_baseline":
+            sig = 0.7 + (0.3 if context_applied else 0.0)
+        else:
+            sig = 0.1
+        sig = min(1.0, sig)
+
+        # Edge filtered + flags
+        if edge_raw is None:
+            edge_filt = None
+            flags = "clean"
+        else:
+            edge_filt = edge_raw
+            applied: list[str] = []
+
+            # Confidence penalty
+            if conf < 0.5:
+                scale = conf / 0.5
+                edge_filt = edge_filt * scale
+                applied.append("conf_penalty")
+
+            # Volatility penalty
+            vol_pen = min(0.02, vol * 0.02)
+            if vol_pen > 0:
+                edge_filt = edge_filt - vol_pen
+                applied.append("vol_penalty")
+
+            # Weak signal suppression
+            if sig < 0.3:
+                edge_filt = edge_filt * 0.5
+                applied.append("weak_signal")
+
+            flags = ",".join(applied) if applied else "clean"
+
+        conf_scores.append(conf)
+        vol_scores.append(vol)
+        sig_scores.append(sig)
+        edge_raws.append(edge_raw)
+        edge_filtered_vals.append(edge_filt)
+        edge_flag_strs.append(flags)
+
+    df["confidence_score"] = conf_scores
+    df["volatility_score"] = vol_scores
+    df["signal_strength_score"] = sig_scores
+    df["edge_raw"] = edge_raws
+    df["edge_filtered"] = edge_filtered_vals
+    df["edge_filter_flags"] = edge_flag_strs
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Task 3 — Timing Heuristics
+# ---------------------------------------------------------------------------
+
+def _compute_timing_fields(df: pd.DataFrame) -> pd.DataFrame:
+    """Add timing_flag, timing_reason."""
+    df = df.copy()
+
+    timing_flags: list[bool] = []
+    timing_reasons: list[str] = []
+
+    for _, row in df.iterrows():
+        reasons: list[str] = []
+
+        # Aggressive price: this book > 2pp better than median (lower implied)
+        this_implied = _safe_implied(row.get("odds_american"))
+        median_price = _safe_float(row.get("median_price"))
+        if (
+            this_implied is not None
+            and median_price is not None
+            and (median_price - this_implied) > AGGRESSIVE_THRESHOLD
+        ):
+            reasons.append("aggressive_price")
+
+        # Timestamp presence
+        has_ts = any(
+            row.get(k) is not None and str(row.get(k)).strip() not in ("", "nan", "None")
+            for k in _TIMESTAMP_KEYS
+        )
+        if has_ts:
+            reasons.append("has_timestamp")
+
+        if not reasons:
+            reasons.append("none")
+
+        timing_flags.append(len(reasons) > 1 or (len(reasons) == 1 and reasons[0] != "none"))
+        timing_reasons.append(",".join(reasons))
+
+    df["timing_flag"] = timing_flags
+    df["timing_reason"] = timing_reasons
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Task 4 — Correlation Awareness
+# ---------------------------------------------------------------------------
+
+def _compute_correlation_fields(df: pd.DataFrame) -> pd.DataFrame:
+    """Add correlation_flag, correlation_direction."""
+    df = df.copy()
+
+    # Count distinct players per game
+    game_keys = df.apply(_make_game_key, axis=1)
+    df["_game_key"] = game_keys
+
+    player_counts: dict[str, int] = {}
+    for key, grp in df.groupby("_game_key"):
+        player_counts[key] = grp["player_name"].nunique()
+
+    corr_directions: list[str] = []
+    for _, row in df.iterrows():
+        key = row["_game_key"]
+        count = player_counts.get(key, 1)
+        corr_directions.append("positive_stacked" if count > 2 else "positive")
+
+    df["correlation_flag"] = True  # always True for HR props
+    df["correlation_direction"] = corr_directions
+
+    df.drop(columns=["_game_key"], inplace=True)
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Task 5 — Final Execution Score
+# ---------------------------------------------------------------------------
+
+def _compute_execution_score(df: pd.DataFrame) -> pd.DataFrame:
+    """Add final_recommendation_score."""
+    df = df.copy()
+
+    scores: list[float | None] = []
+
+    for _, row in df.iterrows():
+        edge_filtered = _safe_float(row.get("edge_filtered"))
+        if edge_filtered is None:
+            scores.append(None)
+            continue
+
+        confidence_score = _safe_float(row.get("confidence_score"), default=0.3)
+        volatility_score = _safe_float(row.get("volatility_score"), default=0.0)
+        market_width = _safe_float(row.get("market_width"), default=0.0)
+        timing_flag = bool(row.get("timing_flag") or False)
+
+        base = edge_filtered * (0.4 + (confidence_score or 0.0) * 0.6)
+        vol_penalty = min(0.015, (volatility_score or 0.0) * 0.015)
+        market_bonus = min(0.01, max(0.0, 0.01 - (market_width or 0.0) * 0.5))
+        timing_bonus = 0.005 if timing_flag else 0.0
+
+        score = base - vol_penalty + market_bonus + timing_bonus
+        score = max(-0.30, min(0.30, score))
+        scores.append(score)
+
+    df["final_recommendation_score"] = scores
+    return df
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def enrich_with_execution_layer(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Run all five execution-layer passes on the mapped props DataFrame.
+
+    Passes (in order):
+      1. Market Disagreement  — best_price, median_price, market_width, flags
+      2. Edge Quality         — confidence, volatility, signal, edge_filtered
+      3. Timing Heuristics    — timing_flag, timing_reason
+      4. Correlation          — correlation_flag, correlation_direction
+      5. Execution Score      — final_recommendation_score
+
+    Returns the enriched DataFrame. Does not modify simulation logic or
+    model probabilities.
+    """
+    if df.empty:
+        return df
+
+    df = _compute_market_fields(df)
+    df = _compute_edge_quality(df)
+    df = _compute_timing_fields(df)
+    df = _compute_correlation_fields(df)
+    df = _compute_execution_score(df)
+    return df

analytics/props_mapper.py

@@ -251,4 +251,12 @@ def map_hr_props_to_model(
     with_edge = hr_df[has_edge].sort_values("edge", ascending=False)
     without_edge = hr_df[~has_edge]
 
-    return pd.concat([with_edge, without_edge], ignore_index=True)
+    result = pd.concat([with_edge, without_edge], ignore_index=True)
+
+    try:
+        from analytics.execution_layer import enrich_with_execution_layer
+        return enrich_with_execution_layer(result)
+    except Exception as exc:
+        from utils.logger import logger
+        logger.warning("execution_layer enrichment failed: %s", exc)
+        return result

analytics/recommendation_engine.py

@@ -92,6 +92,7 @@ def build_upcoming_hitter_recommendations(
     game_row: dict,
     statcast_df: pd.DataFrame,
     odds_df: pd.DataFrame | None = None,
+    prop_odds_df: pd.DataFrame | None = None,
     weather_row: dict | None = None,
 ) -> list[dict]:
     """
@@ -109,9 +110,62 @@ def build_upcoming_hitter_recommendations(
         weather_row=weather_row,
     )
 
+    # Build lookup: normalized_player_name → best HR american odds from real prop feed
+    _prop_odds_lookup: dict[str, int] = {}
+    if prop_odds_df is not None and not prop_odds_df.empty:
+        try:
+            from data.odds_name_map import map_odds_name_to_model_name
+            hr_props = (
+                prop_odds_df[prop_odds_df["market"].isin(["batter_home_runs", "hr"])]
+                if "market" in prop_odds_df.columns
+                else prop_odds_df
+            )
+            if not hr_props.empty and "odds_american" in hr_props.columns and "player_name" in hr_props.columns:
+                # Explicit sort: MAX(odds_american) per player = best price for bettor
+                best_hr = (
+                    hr_props
+                    .sort_values("odds_american", ascending=False)
+                    .drop_duplicates(subset=["player_name"])
+                )
+                for _, prow in best_hr.iterrows():
+                    norm_name = map_odds_name_to_model_name(str(prow.get("player_name") or ""))
+                    odds_val = prow.get("odds_american")
+                    if norm_name and odds_val is not None:
+                        try:
+                            _prop_odds_lookup[norm_name] = int(float(odds_val))
+                        except (TypeError, ValueError):
+                            pass
+        except Exception as exc:
+            logger.warning("[prop_odds_lookup] build failure: %s", exc)
+
     recommendations: list[dict] = []
 
     for row in rows:
+        # Inject real book HR odds if available; fall back to simulator placeholder
+        if _prop_odds_lookup:
+            from data.odds_name_map import map_odds_name_to_model_name
+            _norm_batter = map_odds_name_to_model_name(str(row.get("batter_name") or ""))
+            _real_hr_odds = _prop_odds_lookup.get(_norm_batter)
+
+            # Fallback: raw name match if normalized mapping misses
+            if _real_hr_odds is None:
+                _real_hr_odds = _prop_odds_lookup.get(str(row.get("batter_name") or ""))
+                if _real_hr_odds is not None:
+                    row["book_hr_odds_source"] = "live_feed_unmapped"
+
+            if _real_hr_odds is not None:
+                row["book_hr_odds"] = _real_hr_odds
+                row.setdefault("book_hr_odds_source", "live_feed")
+            else:
+                row.setdefault("book_hr_odds_source", "placeholder")
+                if prop_odds_df is not None and not prop_odds_df.empty:
+                    logger.warning(
+                        "[prop_odds_mapping_miss] batter=%s",
+                        row.get("batter_name"),
+                    )
+        else:
+            row.setdefault("book_hr_odds_source", "placeholder")
+
         slot = row.get("slot", "Current")
         lineup_distance = _lineup_distance_from_slot(slot)
 

app.py

@@ -467,6 +467,22 @@ def load_statcast_recent() -> pd.DataFrame:
     return enriched
 
 
+@st.cache_data(ttl=60, show_spinner=False)
+def load_hr_prop_odds_for_game(away_team: str, home_team: str) -> pd.DataFrame:
+    """Fetch live HR prop odds for a specific game. Returns empty df on failure."""
+    try:
+        from data.live_prop_odds import fetch_live_prop_odds
+        game_context = {"away_team": away_team, "home_team": home_team}
+        df = fetch_live_prop_odds(
+            game_context=game_context,
+            markets=["batter_home_runs"],
+        )
+        return df if df is not None else pd.DataFrame()
+    except Exception as exc:
+        logger.warning("[load_hr_prop_odds_for_game] failure: %s", exc)
+        return pd.DataFrame()
+
+
 @st.cache_data(ttl=REFRESH_TTL_SECONDS)
 def load_odds() -> pd.DataFrame:
     return fetch_featured_odds()
@@ -1998,10 +2014,16 @@ def render_live_games_with_edge_strips(
         with cols[i % 2]:
             render_game_card(game)
 
+            prop_odds_df = load_hr_prop_odds_for_game(
+                away_team=str(game.get("away_team", "")),
+                home_team=str(game.get("home_team", "")),
+            )
+
             recommendations = build_upcoming_hitter_recommendations(
                 game_row=game,
                 statcast_df=statcast_df,
                 odds_df=odds_df,
+                prop_odds_df=prop_odds_df,
                 weather_row=None,
             )
 
@@ -2909,35 +2931,193 @@ def render_bet_tracker() -> None:
     st.plotly_chart(create_bankroll_chart(curve_df), use_container_width=True)
 
 
-def render_algorithm_breakdown() -> None:
-    st.subheader("Algorithm Breakdown")
+def render_alpha_release() -> None:
+    st.subheader("Alpha Release")
+
+    st.info(
+        "**Kasper is in alpha.** Model probabilities are statistical estimates, not guarantees. "
+        "Edge values reflect model output vs. market implied probability — they do not predict outcomes. "
+        "All outputs are for informational and research purposes only."
+    )
+
     st.markdown(
         """
-        ### WBC-first data flow
-        1. Pull official WBC schedule page
-        2. Pull WBC Statcast events from Baseball Savant
-        3. Engineer batter and pitch features
-        4. Build pitcher baseline from recent WBC events
-        5. Score batter-vs-pitcher matchups
-        6. Simulate batter outcomes
-        7. Compare model outputs to no-vig market probabilities
-
-        ### Matchup score inputs
-        - EV90
-        - xwOBA average
-        - release speed
-        - spin rate
-        - movement
-        - venue factor
-        - weather factor
-
-        ### Simulation outputs
-        - hit probability
-        - home run probability
-        - total bases distribution
+        **Kasper** is a pre-game and live-game baseball analytics engine built for the 2026 MLB season.
+        It ingests Statcast data, live game feeds, and sportsbook odds to compute batter HR probabilities,
+        compare them against the market, and surface edges in real time.
+
+        This is an **alpha release** — the model stack is functional and actively processing live data,
+        but outputs are under ongoing validation. Calibration data is accumulating each game day.
         """
     )
 
+    with st.expander("System Overview", expanded=False):
+        st.markdown(
+            """
+            **What Kasper currently supports:**
+            - Live game recommendations (Dashboard) — HR, Hit, Total Bases props for batters On Deck / In Hole / 3 Away
+            - Pre-game HR prop analysis (Props tab) — edge vs. retail books (DraftKings, FanDuel, BetMGM, Caesars)
+            - Execution layer (Alpha) — cross-book market comparison, edge quality filtering, final recommendation score
+            - Full debug visibility — adjustment ladders, signal attribution, execution layer diagnostics
+
+            **Data sources:**
+            - Statcast (Baseball Savant) — batter and pitcher features, 14-day rolling window
+            - MLB Schedule API — live game state, lineup, score
+            - Sportsbook odds API — HR prop odds from retail books
+            """
+        )
+
+    with st.expander("How It Works", expanded=False):
+        st.markdown(
+            """
+            **Signal flow:**
+
+            ```
+            Statcast features
+                → Batter baseline (EV90, barrel rate, hard-hit rate, xwOBA, launch angle)
+                → Pitcher adjustment (velo, EV allowed, barrel rate allowed)
+                → Context adjustments (park, weather, bullpen state)
+                → Zone / arsenal / family-zone matchup overlays
+                → Trend & rolling form (5/10-game windows)
+                → Opportunity adjustment (expected PA given game state)
+                → Fair probability → American odds
+                → Compare vs. sportsbook implied probability
+                → Edge = model prob − book implied prob
+                → Execution layer (market disagreement, confidence, timing, final score)
+                → Recommendation: BET / WATCH / PASS
+            ```
+            """
+        )
+
+    with st.expander("Core Math", expanded=False):
+        st.markdown(
+            r"""
+            **Baseline probability** (per batter, pre-game):
+            - EV90, barrel rate, hard-hit rate, xwOBA, launch angle → weighted sum → bounded probability
+            - Bounds: HR [0.5%, 22%], Hit [5%, 50%], TB2P [3%, 42%]
+
+            **Edge:**
+            ```
+            edge = model_prob − implied_prob(book_odds)
+            ```
+            Positive edge = model believes event is more likely than the market does.
+
+            **Adjusted edge** (live Dashboard):
+            ```
+            adjusted_edge = hr_edge + slot_boost
+            slot_boost: On Deck +1.2pp, In Hole +0.6pp, 3 Away +0.0pp
+            ```
+
+            **Execution score** (Execution Layer):
+            ```
+            base = edge_filtered × (0.4 + confidence × 0.6)
+            score = base − vol_penalty + market_bonus + timing_bonus
+            score clamped to [−0.30, +0.30]
+            ```
+
+            **Recommendation tiers:**
+            - BET: adjusted_edge ≥ 6% AND confidence ≥ 78
+            - WATCH: adjusted_edge ≥ 2.5% AND confidence ≥ 62
+            - PASS: all others
+            """
+        )
+
+    with st.expander("Signal Library", expanded=False):
+        st.markdown(
+            """
+            | Signal | Source | Type |
+            |--------|--------|------|
+            | EV90 | Statcast (90th pct exit velo) | Batter power |
+            | Barrel rate | Statcast | Batter quality contact |
+            | Hard-hit rate | Statcast | Batter contact strength |
+            | xwOBA | Statcast | Batter overall quality |
+            | Launch angle | Statcast | HR trajectory profile |
+            | Pitcher velo | Statcast | Pitcher difficulty |
+            | EV allowed | Statcast | Pitcher weakness |
+            | Zone matchup | Statcast pitch zones | Pitch-to-zone alignment |
+            | Arsenal matchup | Statcast pitch types | Batter vs. pitch family |
+            | Rolling form | 5/10-game window | Recent batter/pitcher trend |
+            | Bullpen state | Live game feed | Leverage / transition risk |
+            | Park factor | Venue lookup | HR environment |
+            | Platoon | Batter/pitcher handedness | Splits adjustment |
+            | Opportunity | Game state (outs, slot) | Expected PA probability |
+            """
+        )
+
+    with st.expander("Execution Layer (Alpha)", expanded=False):
+        st.markdown(
+            """
+            The Execution Layer is a post-model pass that does **not** modify probabilities.
+            It operates on already-computed outputs (model probs + book odds) to improve edge selection.
+
+            **Five passes:**
+            1. **Market Disagreement** — best/median/worst implied prob across books; flags outlier and stale books
+            2. **Edge Quality** — confidence score (source quality), volatility score (market width), signal strength; filters edge_raw → edge_filtered
+            3. **Timing Heuristics** — detects aggressive prices (>2pp better than median) and timestamp presence
+            4. **Correlation** — flags all HR props as positively correlated; detects stacked games (>2 players per game)
+            5. **Final Score** — blends edge_filtered, confidence, volatility, market width, and timing into a [−0.30, +0.30] score
+
+            Visible in: Props tab → "Execution Layer" expander | Debug tab → "Execution Layer (Props)" expander
+            """
+        )
+
+    with st.expander("System Health", expanded=False):
+        st.markdown(
+            """
+            | Feed | Refresh | Notes |
+            |------|---------|-------|
+            | Live game feed | 5s TTL | Live only when games in progress |
+            | Scores | 8s TTL | |
+            | Schedule | 300s TTL | |
+            | Statcast | 600s TTL | 14-day rolling window |
+            | Odds (moneyline) | 30s TTL | Used for Betting tab |
+            | HR props (live, per game) | 60s TTL | Wired into Dashboard recommendations |
+            | HR props (pre-game) | On demand | Via Props tab |
+
+            Data is stored in CockroachDB. Tables: `recommendation_logs`, `upcoming_hr_props`,
+            `batter_prop_outcomes`, `game_outcomes`, `feedback_submissions`.
+            """
+        )
+
+    with st.expander("Alpha Scope", expanded=False):
+        st.markdown(
+            """
+            **Primary focus:** HR props (home run probability)
+
+            HR is the primary market because:
+            - It has the clearest Statcast signal (EV90, barrel rate, launch angle)
+            - It's a binary outcome — clean to evaluate
+            - Books offer consistent retail HR prop lines (DK, FD, BetMGM, Caesars)
+
+            Hit and Total Bases props are computed and displayed but receive less model focus in alpha.
+            """
+        )
+
+    with st.expander("Known Limitations", expanded=False):
+        st.markdown(
+            """
+            - **Pre-game baseline only** (Props tab): No live lineup, park, or weather context. Model uses season Statcast features.
+            - **Live book odds**: When live HR prop odds are unavailable for a game, the Dashboard uses market-neutral reference odds (~+425). These are labeled with `~` in the BOOK column.
+            - **Calibration**: Model has not yet accumulated a full-season outcome dataset. Probability estimates are structurally reasonable but not empirically calibrated to 2026 data.
+            - **Name mapping**: Sportsbook player names sometimes differ from Statcast names. Some players may show "unavailable" source until mapping is added.
+            - **No closing line value (CLV)**: CLV tracking requires final closing odds — not yet wired.
+            - **No account for lineup scratches**: If a player is scratched post-lineup release, the model doesn't know.
+            """
+        )
+
+    with st.expander("Feedback & Roadmap", expanded=False):
+        st.markdown(
+            """
+            Use the **Feedback** tab to submit observations, bugs, or suggestions.
+
+            **Near-term roadmap:**
+            - Post-game outcome grading and calibration reports
+            - Closing line value (CLV) tracking
+            - Hit and Total Bases model calibration
+            - XGBoost model integration (currently shadow mode only)
+            """
+        )
+
 
 def main() -> None:
     render_header()
@@ -2950,7 +3130,7 @@ def main() -> None:
             "Matchups",
             "Betting",
             "Bet Tracker",
-            "Algorithm Breakdown",
+            "Alpha Release",
             "Feedback",
             "Debug",
         ],
@@ -2969,8 +3149,8 @@ def main() -> None:
         render_betting()
     elif page == "Bet Tracker":
         render_bet_tracker()
-    elif page == "Algorithm Breakdown":
-        render_algorithm_breakdown()
+    elif page == "Alpha Release":
+        render_alpha_release()
     elif page == "Feedback":
         render_feedback(conn)
     elif page == "Debug":

data/live_prop_odds.py

@@ -119,7 +119,8 @@ def fetch_live_prop_odds(
             )
             if not df.empty:
                 frames.append(df)
-        except Exception:
+        except Exception as exc:
+            logger.warning("[fetch_live_prop_odds] provider failure: %s", exc)
             continue
 
     if not frames:

visualization/debug_page.py

@@ -390,6 +390,35 @@ def render_debug(
             else:
                 st.info("Bullpen candidate data not available.")
 
+    # ------------------------------------------------------------------
+    # SECTION 5c — Execution Layer
+    # ------------------------------------------------------------------
+    exec_df = st.session_state.get("props_exec_df")
+    with st.expander("Execution Layer (Props)", expanded=False):
+        if exec_df is None or (isinstance(exec_df, pd.DataFrame) and exec_df.empty):
+            st.info("No execution layer data. Visit the Props tab first.")
+        else:
+            exec_cols = [
+                "player_name", "sportsbook",
+                "edge_raw", "edge_filtered", "confidence_score",
+                "volatility_score", "signal_strength_score",
+                "market_width", "market_outlier_flag", "stale_book_flag",
+                "timing_flag", "timing_reason",
+                "correlation_flag", "correlation_direction",
+                "final_recommendation_score", "edge_filter_flags",
+            ]
+            available = [c for c in exec_cols if c in exec_df.columns]
+            if available:
+                sort_col = "final_recommendation_score"
+                display_exec = exec_df[available].copy()
+                if sort_col in display_exec.columns:
+                    display_exec = display_exec.sort_values(
+                        sort_col, ascending=False, na_position="last"
+                    )
+                st.dataframe(display_exec, use_container_width=True, hide_index=True)
+            else:
+                st.info("Execution layer fields not present in props data.")
+
     # ------------------------------------------------------------------
     # SECTION 6 — Admin Tools
     # ------------------------------------------------------------------

visualization/props_page.py

@@ -91,6 +91,7 @@ def render_props(statcast_df: pd.DataFrame, conn=None) -> None:
         if mapped.empty:
             st.info("No mappable HR prop rows.")
             return
+        st.session_state["props_exec_df"] = mapped
 
         # Log to durable DB (non-blocking)
         if conn is not None:
@@ -252,6 +253,22 @@ def render_props(statcast_df: pd.DataFrame, conn=None) -> None:
     table_df = pd.DataFrame(rows)
     st.dataframe(table_df, use_container_width=True, hide_index=True)
 
+    if market_type == "hr" and "final_recommendation_score" in display.columns:
+        with st.expander("Execution Layer", expanded=False):
+            exec_cols = [
+                "player_name", "sportsbook",
+                "edge_raw", "edge_filtered", "confidence_score",
+                "volatility_score", "signal_strength_score",
+                "market_width", "market_outlier_flag", "stale_book_flag",
+                "timing_flag", "correlation_flag",
+                "final_recommendation_score", "edge_filter_flags",
+            ]
+            exec_display = display[[c for c in exec_cols if c in display.columns]].copy()
+            exec_display = exec_display.sort_values(
+                "final_recommendation_score", ascending=False, na_position="last"
+            )
+            st.dataframe(exec_display, use_container_width=True, hide_index=True)
+
     # ---------------------------------------------------------------------------
     # Disclaimer (HR only)
     # ---------------------------------------------------------------------------

visualization/recommendation_panels.py

@@ -124,6 +124,16 @@ def render_recommendation_panels(rows: list[dict[str, Any]]) -> None:
 
         badges_html = _fmt_badges(row.get("opportunity_badges", []))
 
+        _book_src = str(row.get("book_hr_odds_source") or "placeholder")
+        _book_odds_raw = _fmt_odds(row.get("book_hr_odds"))
+        if _book_src == "placeholder":
+            _book_display = (
+                f'<span title="Reference odds (market data unavailable)" '
+                f'style="color:#64748b;">~{_book_odds_raw}</span>'
+            )
+        else:
+            _book_display = _book_odds_raw
+
         body_rows.append(
             f"""
             <div class="row-wrap">
@@ -134,7 +144,7 @@ def render_recommendation_panels(rows: list[dict[str, Any]]) -> None:
                   <div class="reason-line">{reason_text}</div>
                 </div>
                 <div>{_fmt_odds(row.get("fair_hr_odds"))}</div>
-                <div>{_fmt_odds(row.get("book_hr_odds"))}</div>
+                <div>{_book_display}</div>
                 <div>{_fmt_edge(row.get("adjusted_edge", row.get("hr_edge")))}</div>
                 <div>{_fmt_confidence(row.get("confidence"))}</div>
                 <div>{_fmt_tier(row.get("recommendation_tier"))}</div>