"""Deterministic recommendation eligibility logic.

Evaluates trend summaries against configurable thresholds to decide:
- Whether a recommendation should be generated at all
- What action type (buy/sell/hold/watch) is appropriate
- What execution mode (informational/paper_eligible/live_eligible) is allowed
- Position sizing guidance based on portfolio rules

All decisions are rule-based with no model involvement. The LLM is only
used downstream for optional thesis wording (a separate task).

Requirements: 7.1, 7.2, 7.3, 7.4, 14.1, 14.2, 14.3, 14.4, 14.5, 14.6

v3 additions:
- ReturnDistribution and EV gate (Requirement 12)
- Regime-aware eligibility and mode escalation (Requirements 13.1–13.5)
"""
from __future__ import annotations

import math
from dataclasses import dataclass, field
from enum import Enum

from services.shared.schemas import (
    ActionType,
    PositionSizing,
    RecommendationMode,
    TrendDirection,
    TrendSummary,
)


class RejectionReason(str, Enum):
    """Why a trend summary was deemed ineligible for a recommendation."""

    LOW_CONFIDENCE = "low_confidence"
    LOW_TREND_STRENGTH = "low_trend_strength"
    HIGH_CONTRADICTION = "high_contradiction"
    INSUFFICIENT_EVIDENCE = "insufficient_evidence"
    NEUTRAL_DIRECTION = "neutral_direction"


@dataclass(frozen=True)
class EligibilityConfig:
    """Tunable thresholds for recommendation eligibility.

    All thresholds are deterministic — no model inference involved.
    """

    # --- Gate thresholds (below these → no recommendation) ---
    min_confidence: float = 0.35
    min_trend_strength: float = 0.10
    max_contradiction_score: float = 0.60
    min_evidence_count: int = 2  # combined supporting + opposing

    # --- Action mapping thresholds ---
    # Trend strength above this → buy/sell; below → hold/watch
    action_strength_threshold: float = 0.25
    # Confidence above this → hold (rather than watch) for weak signals
    hold_confidence_threshold: float = 0.50

    # --- Mode escalation thresholds ---
    # Confidence required for paper_eligible (below → informational)
    paper_confidence_threshold: float = 0.50
    # Confidence required for live_eligible (below → paper at most)
    live_confidence_threshold: float = 0.70
    # Contradiction must be below this for live eligibility
    live_max_contradiction: float = 0.25
    # Minimum evidence count for live eligibility
    live_min_evidence: int = 5

    # --- Position sizing rules (Requirement 7.3) ---
    # Base portfolio allocation percentage
    base_portfolio_pct: float = 0.01
    # Maximum portfolio allocation percentage
    max_portfolio_pct: float = 0.10
    # Base max loss percentage
    base_max_loss_pct: float = 0.003
    # Maximum max loss percentage
    max_max_loss_pct: float = 0.02
    # Confidence scaling: higher confidence → larger position (linear)
    confidence_sizing_weight: float = 0.8
    # Contradiction penalty: higher contradiction → smaller position
    contradiction_sizing_penalty: float = 0.5

    # --- Expected value gate (Requirement 14) ---
    # EV threshold: minimum expected value to allow recommendation through
    ev_threshold: float = 0.005


DEFAULT_ELIGIBILITY_CONFIG = EligibilityConfig()


@dataclass
class EligibilityResult:
    """Output of the deterministic eligibility evaluation.

    Captures the decision, the reasoning, and all inputs used so the
    full decision trace is reproducible (Requirement 8.3).
    """

    eligible: bool
    action: ActionType
    mode: RecommendationMode
    position_sizing: PositionSizing
    rejection_reasons: list[RejectionReason] = field(default_factory=list)
    time_horizon: str = ""
    invalidation_conditions: list[str] = field(default_factory=list)

    # Probabilistic pipeline fields (Req 14.5, 16.2)
    ev_value: float | None = None
    p_bull: float | None = None
    pipeline_mode: str = "heuristic"


# ---------------------------------------------------------------------------
# Gate checks
# ---------------------------------------------------------------------------


def _check_gates(
    summary: TrendSummary,
    config: EligibilityConfig,
) -> list[RejectionReason]:
    """Apply hard gate checks. Returns a list of rejection reasons (empty = pass)."""
    reasons: list[RejectionReason] = []

    if summary.confidence < config.min_confidence:
        reasons.append(RejectionReason.LOW_CONFIDENCE)

    if summary.trend_strength < config.min_trend_strength:
        reasons.append(RejectionReason.LOW_TREND_STRENGTH)

    if summary.contradiction_score > config.max_contradiction_score:
        reasons.append(RejectionReason.HIGH_CONTRADICTION)

    evidence_count = len(summary.top_supporting_evidence) + len(summary.top_opposing_evidence)
    if evidence_count < config.min_evidence_count:
        reasons.append(RejectionReason.INSUFFICIENT_EVIDENCE)

    if summary.trend_direction == TrendDirection.NEUTRAL:
        reasons.append(RejectionReason.NEUTRAL_DIRECTION)

    return reasons


# ---------------------------------------------------------------------------
# Action mapping
# ---------------------------------------------------------------------------


def _determine_action(
    summary: TrendSummary,
    config: EligibilityConfig,
) -> ActionType:
    """Map trend direction and strength to an action type.

    Strong bullish → BUY, strong bearish → SELL.
    Weak but directional → HOLD if confidence is decent, else WATCH.
    Mixed → WATCH.
    """
    direction = summary.trend_direction
    strength = summary.trend_strength

    if direction == TrendDirection.MIXED:
        return ActionType.WATCH

    if direction == TrendDirection.NEUTRAL:
        return ActionType.WATCH

    strong_signal = strength >= config.action_strength_threshold

    if direction == TrendDirection.BULLISH:
        if strong_signal:
            return ActionType.BUY
        return ActionType.HOLD if summary.confidence >= config.hold_confidence_threshold else ActionType.WATCH

    if direction == TrendDirection.BEARISH:
        if strong_signal:
            return ActionType.SELL
        return ActionType.HOLD if summary.confidence >= config.hold_confidence_threshold else ActionType.WATCH

    return ActionType.WATCH


# ---------------------------------------------------------------------------
# Mode escalation
# ---------------------------------------------------------------------------


def _determine_mode(
    summary: TrendSummary,
    action: ActionType,
    config: EligibilityConfig,
) -> RecommendationMode:
    """Determine the highest execution mode allowed.

    WATCH and HOLD actions are always informational — they don't trigger trades.
    BUY/SELL can escalate to paper_eligible or live_eligible based on
    confidence, contradiction, and evidence thresholds.
    """
    if action in (ActionType.WATCH, ActionType.HOLD):
        return RecommendationMode.INFORMATIONAL

    evidence_count = len(summary.top_supporting_evidence) + len(summary.top_opposing_evidence)

    # Check live eligibility first (strictest)
    if (
        summary.confidence >= config.live_confidence_threshold
        and summary.contradiction_score <= config.live_max_contradiction
        and evidence_count >= config.live_min_evidence
    ):
        return RecommendationMode.LIVE_ELIGIBLE

    # Check paper eligibility
    if summary.confidence >= config.paper_confidence_threshold:
        return RecommendationMode.PAPER_ELIGIBLE

    return RecommendationMode.INFORMATIONAL


# ---------------------------------------------------------------------------
# Position sizing (Requirement 7.3)
# ---------------------------------------------------------------------------


def _compute_position_sizing(
    summary: TrendSummary,
    config: EligibilityConfig,
) -> PositionSizing:
    """Compute position sizing guidance from portfolio rules and signal quality.

    Higher confidence and trend strength → larger allocation (up to max).
    Higher contradiction → smaller allocation (penalty).
    Low evidence count further reduces allocation.
    """
    # Confidence-based scaling over the full range
    confidence_factor = config.confidence_sizing_weight * summary.confidence
    # Trend strength multiplier — stronger trends justify larger positions
    strength_factor = 0.5 + 0.5 * summary.trend_strength  # range [0.5, 1.0]

    portfolio_range = config.max_portfolio_pct - config.base_portfolio_pct
    raw_portfolio = config.base_portfolio_pct + confidence_factor * strength_factor * portfolio_range

    # Apply contradiction penalty
    contradiction_penalty = config.contradiction_sizing_penalty * summary.contradiction_score
    portfolio_pct = raw_portfolio * (1.0 - contradiction_penalty)

    # Evidence count penalty — fewer sources = less confidence in sizing
    evidence_count = len(summary.top_supporting_evidence) + len(summary.top_opposing_evidence)
    if evidence_count < 3:
        portfolio_pct *= 0.5
    elif evidence_count < 5:
        portfolio_pct *= 0.75

    # Clamp to bounds
    portfolio_pct = max(config.base_portfolio_pct * 0.5, min(portfolio_pct, config.max_portfolio_pct))

    # Max loss scales similarly
    loss_range = config.max_max_loss_pct - config.base_max_loss_pct
    raw_loss = config.base_max_loss_pct + confidence_factor * strength_factor * loss_range
    max_loss_pct = raw_loss * (1.0 - contradiction_penalty)
    if evidence_count < 3:
        max_loss_pct *= 0.5
    elif evidence_count < 5:
        max_loss_pct *= 0.75
    max_loss_pct = max(config.base_max_loss_pct * 0.5, min(max_loss_pct, config.max_max_loss_pct))

    return PositionSizing(
        portfolio_pct=round(portfolio_pct, 6),
        max_loss_pct=round(max_loss_pct, 6),
    )


# ---------------------------------------------------------------------------
# Time horizon mapping
# ---------------------------------------------------------------------------

_WINDOW_TO_HORIZON: dict[str, str] = {
    "intraday": "intraday",
    "1d": "swing_1d_3d",
    "7d": "swing_1d_10d",
    "30d": "position_10d_30d",
    "90d": "position_30d_90d",
}


def _map_time_horizon(window: str) -> str:
    """Map a trend window to a human-readable time horizon label."""
    return _WINDOW_TO_HORIZON.get(window, f"window_{window}")


# ---------------------------------------------------------------------------
# Invalidation conditions
# ---------------------------------------------------------------------------


def _derive_invalidation_conditions(
    summary: TrendSummary,
    action: ActionType,
) -> list[str]:
    """Generate deterministic invalidation conditions for the recommendation.

    These describe when the recommendation should be considered stale or wrong.
    """
    conditions: list[str] = []

    if action == ActionType.BUY:
        conditions.append(
            f"Trend direction for {summary.entity_id} reverses to bearish"
        )
    elif action == ActionType.SELL:
        conditions.append(
            f"Trend direction for {summary.entity_id} reverses to bullish"
        )

    if summary.contradiction_score > 0.0:
        conditions.append(
            f"Contradiction score exceeds 0.60 (currently {summary.contradiction_score:.2f})"
        )

    if summary.confidence > 0.0:
        conditions.append(
            f"Confidence drops below {summary.confidence * 0.7:.2f}"
        )

    if summary.material_risks:
        conditions.append(
            f"Material risk materialises: {summary.material_risks[0]}"
        )

    return conditions


# ---------------------------------------------------------------------------
# Expected value computation (Requirements: 14.1–14.6)
# ---------------------------------------------------------------------------

# Horizon days mapping for EV computation
_EV_HORIZON_DAYS: dict[str, float] = {
    "intraday": 1.0,
    "1d": 1.0,
    "7d": 7.0,
    "30d": 30.0,
    "90d": 90.0,
}


def compute_expected_value(
    p_bull: float,
    strength: float,
    sigma_20: float,
    horizon_days: float,
) -> float:
    """Compute expected value for the recommendation gate.

    Formula:
        R_up   = strength · σ_20 · √(horizon_days)
        R_down = (1 - strength) · σ_20 · √(horizon_days)
        EV     = P_bull · R_up - P_bear · R_down

    where P_bear = 1 - P_bull.

    Args:
        p_bull: Bayesian bullish probability in [0, 1].
        strength: Trend strength in [0, 1].
        sigma_20: 20-day return standard deviation.
        horizon_days: Number of days for the projection horizon.

    Returns:
        Expected value (can be negative).

    Requirements: 14.1, 14.2
    """
    p_bear = 1.0 - p_bull
    sqrt_horizon = math.sqrt(max(horizon_days, 0.0))
    r_up = strength * sigma_20 * sqrt_horizon
    r_down = (1.0 - strength) * sigma_20 * sqrt_horizon
    ev = p_bull * r_up - p_bear * r_down
    # Guard against NaN/infinity from extreme inputs
    if math.isnan(ev) or math.isinf(ev):
        return 0.0
    return ev


# ---------------------------------------------------------------------------
# Main entry point
# ---------------------------------------------------------------------------


def evaluate_eligibility(
    summary: TrendSummary,
    config: EligibilityConfig = DEFAULT_ELIGIBILITY_CONFIG,
    *,
    probabilistic: bool = False,
    p_bull: float | None = None,
    sigma_20: float = 0.01,
) -> EligibilityResult:
    """Evaluate a trend summary for recommendation eligibility.

    This is the single deterministic entry point. It:
    1. Applies gate checks (confidence, strength, contradiction, evidence)
    2. Maps trend direction + strength to an action type
    3. Determines the highest allowed execution mode
    4. Computes position sizing from portfolio rules
    5. Derives invalidation conditions
    6. (probabilistic) Applies EV gate: EV > threshold to proceed

    When ``probabilistic=True``:
    - Computes EV = P_bull · R_up - P_bear · R_down
    - When EV > threshold (default 0.005), allows recommendation through
    - When EV ≤ threshold, forces recommendation to informational mode
    - Populates expected_value, p_bull, pipeline_mode on result

    When ``probabilistic=False``:
    - Skips EV gate entirely (existing behavior)

    Args:
        summary: The current trend summary.
        config: Eligibility configuration thresholds.
        probabilistic: Use EV gate when True.
        p_bull: Bayesian bullish probability (required when probabilistic=True).
        sigma_20: 20-day return standard deviation for EV computation.

    Returns an EligibilityResult with the full decision trace.

    Requirements: 14.1, 14.2, 14.3, 14.4, 14.5, 14.6
    """
    rejection_reasons = _check_gates(summary, config)

    # Even if rejected, we still compute action/mode for the trace
    action = _determine_action(summary, config)
    mode = _determine_mode(summary, action, config)
    sizing = _compute_position_sizing(summary, config)
    horizon = _map_time_horizon(summary.window.value)
    invalidation = _derive_invalidation_conditions(summary, action)

    eligible = len(rejection_reasons) == 0

    # If not eligible, force mode to informational (Requirement 7.4)
    if not eligible:
        mode = RecommendationMode.INFORMATIONAL

    # EV gate (Requirement 14.1–14.6)
    ev_value: float | None = None
    if probabilistic and p_bull is not None:
        horizon_days = _EV_HORIZON_DAYS.get(summary.window.value, 7.0)
        ev_value = compute_expected_value(
            p_bull=p_bull,
            strength=summary.trend_strength,
            sigma_20=sigma_20,
            horizon_days=horizon_days,
        )

        if ev_value <= config.ev_threshold:
            # Force to informational mode (Req 14.4)
            mode = RecommendationMode.INFORMATIONAL

    return EligibilityResult(
        eligible=eligible,
        action=action,
        mode=mode,
        position_sizing=sizing,
        rejection_reasons=rejection_reasons,
        time_horizon=horizon,
        invalidation_conditions=invalidation,
        ev_value=ev_value,
        p_bull=p_bull if probabilistic else None,
        pipeline_mode="probabilistic" if probabilistic else "heuristic",
    )


# ---------------------------------------------------------------------------
# V3 Return Distribution and EV Gate (Requirements 12.1–12.7)
# ---------------------------------------------------------------------------

_V3_MIN_EDGE: dict[str, float] = {
    "panic": 0.0100,
    "trend_following": 0.0035,
    "mean_reversion": 0.0050,
    "uncertainty": 0.0075,
}

_V3_ELIGIBILITY_THRESHOLDS: dict[str, tuple[float, float, float]] = {
    # (confidence_min, contradiction_max, strength_min)
    "panic": (0.70, 0.25, 0.36),
    "trend_following": (0.55, 0.40, 0.20),
    "mean_reversion": (0.60, 0.35, 0.26),
    "uncertainty": (0.65, 0.30, 0.30),
}


@dataclass(frozen=True)
class ReturnDistribution:
    """V3 return distribution model output.

    Encapsulates the horizon-scaled volatility, expected return, risk-adjusted
    expected value, regime minimum edge, and final eligibility decision.

    Requirements: 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7
    """

    sigma_h: float  # realized_vol_20d * sqrt(horizon_days / 252)
    mu_h: float  # tanh(A_projected / 3.0) * confidence * sigma_h
    ev_long: float  # mu_h - costs - 0.10 * CVaR_5
    min_edge: float  # regime-specific minimum edge
    eligible: bool


def compute_return_distribution(
    a_projected: float,
    confidence: float,
    realized_vol_20d: float,
    horizon_days: int,
    costs: float,
    regime: str,
    *,
    confidence_actual: float = 1.0,
    contradiction: float = 0.0,
    n_eff_total: float = 0.0,
    data_quality: float = 1.0,
) -> ReturnDistribution:
    """Compute the v3 return distribution and EV gate eligibility.

    Implements the return distribution model from the v3 math spec:
    - sigma_h: horizon-scaled volatility
    - mu_h: expected return using tanh-compressed projected alpha
    - CVaR_5: Gaussian approximation of 5th percentile tail loss
    - EV_long: risk-adjusted expected value after costs and tail risk

    Eligibility requires:
    - EV_long > regime min_edge
    - EV_long > max(0.0025, 0.25 * costs)
    - confidence_actual >= regime confidence_min
    - contradiction <= regime contradiction_max
    - n_eff_total >= 2.0
    - data_quality >= 0.50

    Args:
        a_projected: Projected evidence state A_projected_h from projection.
        confidence: Multiplicative confidence from the v3 pipeline.
        realized_vol_20d: 20-day realized annualized volatility.
            If <= 0 or unavailable, defaults to 0.25.
        horizon_days: Trading days for the horizon (1, 7, 30, or 90).
        costs: Total costs (spread + slippage + commission).
        regime: Market regime string (panic, trend_following, mean_reversion, uncertainty).
        confidence_actual: The raw confidence value for threshold checks (defaults to
            same as confidence if not separately provided).
        contradiction: Contradiction score in [0, 1].
        n_eff_total: Total effective evidence count across clusters.
        data_quality: Data quality score in [0, 1].

    Returns:
        ReturnDistribution with computed fields and eligibility decision.

    Requirements: 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7
    """
    # Default volatility when unavailable (Req 12.7)
    if realized_vol_20d is None or realized_vol_20d <= 0:  # type: ignore[redundant-expr]
        realized_vol_20d = 0.25

    # Req 12.1: sigma_h = realized_vol_20d * sqrt(horizon_days / 252)
    sigma_h = realized_vol_20d * math.sqrt(horizon_days / 252.0)

    # Req 12.2: mu_h = tanh(A_projected / 3.0) * confidence * sigma_h
    mu_h = math.tanh(a_projected / 3.0) * confidence * sigma_h

    # Req 12.3: CVaR_5 = sigma_h * 1.645 * 1.4
    cvar_5 = sigma_h * 1.645 * 1.4

    # Req 12.3: EV_long = mu_h - costs - 0.10 * CVaR_5
    ev_long = mu_h - costs - 0.10 * cvar_5

    # Req 12.4: regime-specific min_edge
    min_edge = _V3_MIN_EDGE.get(regime, _V3_MIN_EDGE["uncertainty"])

    # Req 12.5: EV_long > min_edge AND EV_long > max(0.0025, 0.25 * costs)
    ev_gate_passed = ev_long > min_edge and ev_long > max(0.0025, 0.25 * costs)

    # Req 12.6: Additional eligibility checks
    thresholds = _V3_ELIGIBILITY_THRESHOLDS.get(
        regime, _V3_ELIGIBILITY_THRESHOLDS["uncertainty"]
    )
    confidence_min, contradiction_max, _strength_min = thresholds

    quality_gate_passed = (
        confidence_actual >= confidence_min
        and contradiction <= contradiction_max
        and n_eff_total >= 2.0
        and data_quality >= 0.50
    )

    eligible = ev_gate_passed and quality_gate_passed

    return ReturnDistribution(
        sigma_h=sigma_h,
        mu_h=mu_h,
        ev_long=ev_long,
        min_edge=min_edge,
        eligible=eligible,
    )


# ===========================================================================
# v3 Regime-Aware Eligibility and Mode Escalation (Requirements 13.1–13.5)
# ===========================================================================

# Direction thresholds for action mapping (from bayesian.py)
_V3_DIRECTION_THRESHOLDS: dict[str, tuple[float, float]] = {
    "panic": (0.68, 0.32),
    "trend_following": (0.60, 0.40),
    "mean_reversion": (0.63, 0.37),
    "uncertainty": (0.65, 0.35),
}


@dataclass(frozen=True)
class V3Eligibility:
    """Result of v3 regime-aware eligibility evaluation.

    Requirements: 13.1–13.5
    """

    action: str  # "BUY", "SELL", "HOLD", "WATCH"
    mode: str  # "live", "paper", "informational"
    eligible: bool  # meets regime thresholds
    reasons: list[str]  # reasons for non-eligibility or downgrade


def compute_v3_eligibility(
    p_up: float,
    ev_long: float,
    min_edge: float,
    confidence: float,
    contradiction: float,
    strength: float,
    n_eff_total: float,
    data_quality: float,
    regime: str,
    has_existing_position: bool = False,
    risk_engine_passed: bool = True,
) -> V3Eligibility:
    """Compute regime-aware eligibility and mode escalation.

    Requirements: 13.1–13.5

    Steps:
    1. Check regime-specific eligibility gates (confidence, contradiction, strength)
    2. Determine action (BUY/SELL/HOLD/WATCH) based on P_up and EV
    3. Escalate mode (live/paper/informational) based on signal quality

    Args:
        p_up: Posterior probability of upward move from Bayesian posterior.
        ev_long: Expected value from return distribution.
        min_edge: Regime-specific minimum edge from EV gate.
        confidence: Multiplicative confidence score in [0, 1].
        contradiction: LLR entropy contradiction in [0, 1].
        strength: Signal strength = abs(2 * P_up - 1).
        n_eff_total: Effective evidence count across all clusters.
        data_quality: Data quality score in [0, 1].
        regime: Current market regime string.
        has_existing_position: Whether the entity already has an open position.
        risk_engine_passed: Whether the risk engine approved the trade.

    Returns:
        V3Eligibility with action, mode, eligible flag, and reasons.
    """
    reasons: list[str] = []

    # --- 1. Regime-specific eligibility gates (Requirement 13.1) ---
    conf_min, contra_max, str_min = _V3_ELIGIBILITY_THRESHOLDS.get(
        regime, (0.65, 0.30, 0.30)  # default to uncertainty thresholds
    )

    eligible = True

    if confidence < conf_min:
        eligible = False
        reasons.append(f"confidence {confidence:.3f} < regime min {conf_min:.2f}")

    if contradiction > contra_max:
        eligible = False
        reasons.append(
            f"contradiction {contradiction:.3f} > regime max {contra_max:.2f}"
        )

    if strength < str_min:
        eligible = False
        reasons.append(f"strength {strength:.3f} < regime min {str_min:.2f}")

    if data_quality < 0.50:
        eligible = False
        reasons.append(f"data_quality {data_quality:.3f} < 0.50")

    if n_eff_total < 2.0:
        eligible = False
        reasons.append(f"n_eff_total {n_eff_total:.2f} < 2.0")

    # --- 2. Action mapping (Requirement 13.2) ---
    bull_thresh, _bear_thresh = _V3_DIRECTION_THRESHOLDS.get(
        regime, (0.65, 0.35)
    )

    if not eligible:
        action = "WATCH"
    elif p_up >= bull_thresh and ev_long > min_edge:
        action = "BUY"
    elif has_existing_position and ev_long <= 0:
        # SELL when existing position and exit EV > hold EV
        # Simplified: EV_exit > EV_hold approximated as ev_long <= 0
        # (holding has negative expected value → better to exit)
        action = "SELL"
    elif has_existing_position:
        action = "HOLD"
    else:
        action = "WATCH"

    # --- 3. Mode escalation (Requirements 13.3, 13.4, 13.5) ---
    if action in ("BUY", "SELL"):
        # Check live eligibility (Requirement 13.3)
        if (
            confidence >= 0.75
            and contradiction <= 0.20
            and n_eff_total >= 5
            and ev_long > 2 * min_edge
            and risk_engine_passed
        ):
            mode = "live"
        # Check paper eligibility (Requirement 13.4)
        elif (
            confidence >= 0.60
            and ev_long > min_edge
            and risk_engine_passed
        ):
            mode = "paper"
        else:
            mode = "informational"
            if confidence < 0.60:
                reasons.append(
                    f"paper requires confidence >= 0.60, got {confidence:.3f}"
                )
            if ev_long <= min_edge:
                reasons.append(
                    f"paper requires EV > min_edge ({min_edge:.4f}), got {ev_long:.4f}"
                )
            if not risk_engine_passed:
                reasons.append("risk engine did not pass")
    else:
        # HOLD and WATCH are always informational (Requirement 13.5)
        mode = "informational"

    return V3Eligibility(
        action=action,
        mode=mode,
        eligible=eligible,
        reasons=reasons,
    )