exp_1154

FORMULA_NAME = "Explore Regime Momentum Recovery Quality Hybrid (Admission Relay, v1154)"
LOGIC_VARIANT_COUNT = 4
NOTES = """mode=explore; family=regime-momentum-recovery-quality-hybrid
New hybrid family built as an admission relay rather than a static blend: momentum leadership, recovery repair, and quality-income franchise sleeves all compete for entry, and the regime branch decides which sleeve is allowed to dominate when signals conflict. The explicit arbitration is stock-level: strong momentum only clears if trend is intact, deep drawdowns only clear if repair plus franchise support are present, and defensive franchise names outrank both when tape quality deteriorates.
Deliberate metric coverage this run: active momentum uses 1m/3m/6m plus 12_1 selectively; trend/recovery uses both 200d distance and 52-week-high distance; volatility is active through realized vol; liquidity uses all three liquidity/continuity metrics; income uses both dividend yield and dividend cash; valuation rotates to pe and forward_pe while peg is deliberately zeroed; growth rotates to eps growth, revenue growth, and forward_eps while operating-income/free-cash-flow growth are deliberately zeroed; quality uses both operating and free-cash-flow margins; size is used only as a defensive large-cap admission tilt via raw market_cap gates, not as a raw z-score rank. Deliberate weight-0 metrics: return_12m_pct, peg, operating_income_growth_pct, free_cash_flow_growth_pct, shares_outstanding, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, free_cash_flow_ttm."""

LEADER_CLUSTER = {
    "momentum_12_1_pct": (0.34, +1),
    "return_6m_pct": (0.29, +1),
    "return_3m_pct": (0.21, +1),
    "from_200d_ma_pct": (0.16, +1),
}

REBUILD_CLUSTER = {
    "from_200d_ma_pct": (0.30, +1),
    "from_52w_high_pct": (0.26, -1),
    "return_3m_pct": (0.18, +1),
    "return_1m_pct": (0.14, -1),
    "momentum_12_1_pct": (0.12, +1),
}

FRANCHISE_CLUSTER = {
    "operating_margin_pct": (0.25, +1),
    "free_cash_flow_margin_pct": (0.23, +1),
    "eps_growth_pct": (0.18, +1),
    "revenue_growth_pct": (0.14, +1),
    "forward_eps": (0.12, +1),
    "forward_pe": (0.08, -1),
}

STABILITY_CLUSTER = {
    "realized_vol_3m": (0.34, -1),
    "trading_days_3m": (0.24, +1),
    "avg_daily_dollar_volume_3m": (0.24, +1),
    "avg_daily_volume_3m": (0.18, +1),
}

INCOME_VALUE_CLUSTER = {
    "dividend_yield_ttm_pct": (0.28, +1),
    "dividend_ttm": (0.18, +1),
    "pe": (0.28, -1),
    "forward_pe": (0.26, -1),
}

WASHOUT_CLUSTER = {
    "from_52w_high_pct": (0.50, -1),
    "return_1m_pct": (0.30, -1),
    "realized_vol_3m": (0.20, +1),
}


def score_universe(stocks, regime, ctx):
    z_cache = {}

    def z(metric, symbol):
        series = z_cache.get(metric)
        if series is None:
            series = ctx.z(metric)
            z_cache[metric] = series
        if not series:
            return None
        return series.get(symbol)

    def blend(symbol, spec):
        total = 0.0
        used = 0.0
        for metric, (weight, sign) in spec.items():
            value = z(metric, symbol)
            if value is None:
                continue
            total += weight * sign * value
            used += weight
        if used == 0.0:
            return 0.0
        return total / used

    def clamp(value, lo, hi):
        if value < lo:
            return lo
        if value > hi:
            return hi
        return value

    breadth = regime.get("breadth")
    avg_vol = regime.get("avg_realized_vol_3m")
    median_trend = regime.get("median_from_200d_ma_pct")
    median_momo = regime.get("median_momentum_12_1_pct")

    if breadth is None:
        breadth = 0.5
    if avg_vol is None:
        avg_vol = 0.0
    if median_trend is None:
        median_trend = 0.0
    if median_momo is None:
        median_momo = 0.0

    if regime.get("bull") and breadth >= 0.62 and median_trend >= 1.5 and median_momo >= 1.0:
        branch = "impulse"
    elif breadth >= 0.52 and avg_vol < 33.0 and median_trend >= -1.0:
        branch = "rotation"
    elif breadth >= 0.40 and avg_vol < 43.0 and median_trend >= -7.0:
        branch = "rebuild"
    else:
        branch = "defense"

    scores = {}
    for stock in stocks:
        symbol = stock["symbol"]

        leader = blend(symbol, LEADER_CLUSTER)
        rebuild = blend(symbol, REBUILD_CLUSTER)
        franchise = blend(symbol, FRANCHISE_CLUSTER)
        stability = blend(symbol, STABILITY_CLUSTER)
        income_value = blend(symbol, INCOME_VALUE_CLUSTER)
        washout = blend(symbol, WASHOUT_CLUSTER)

        from_200d = stock.get("from_200d_ma_pct")
        if from_200d is None:
            from_200d = -999.0
        from_high = stock.get("from_52w_high_pct")
        if from_high is None:
            from_high = -999.0
        ret_1m = stock.get("return_1m_pct")
        if ret_1m is None:
            ret_1m = 0.0
        ret_3m = stock.get("return_3m_pct")
        if ret_3m is None:
            ret_3m = -999.0
        realized_vol = stock.get("realized_vol_3m")
        if realized_vol is None:
            realized_vol = 999.0
        trading_days = stock.get("trading_days_3m")
        if trading_days is None:
            trading_days = 0.0
        market_cap = stock.get("market_cap")
        if market_cap is None:
            market_cap = 0.0

        trend_intact = from_200d > 0.0 and ret_3m > 0.0
        near_high = from_high > -14.0
        deep_pullback = from_high < -24.0
        repaired = from_200d > -10.0 and ret_3m > -2.0
        liquid = trading_days >= 45.0
        large_cap_defense = market_cap >= 15000000000.0

        leader_ready = leader > 0.18 and trend_intact and near_high
        rebuild_ready = rebuild > 0.10 and repaired and franchise > -0.10 and stability > -0.15 and liquid
        franchise_ready = franchise > 0.12 and stability > 0.0 and liquid
        falling_knife = deep_pullback and rebuild < -0.05 and franchise < -0.05
        false_strength = leader > 0.35 and from_200d < -2.0
        exhausted = ret_1m > 18.0 and realized_vol > 55.0

        state = "unproven"
        if leader_ready:
            state = "leader"
        elif rebuild_ready and washout > 0.05:
            state = "rebuild"
        elif franchise_ready:
            state = "franchise"

        conflict_penalty = 0.0
        if false_strength:
            conflict_penalty += 0.18
        if leader - rebuild > 1.10 and not near_high:
            conflict_penalty += 0.12 * (leader - rebuild)
        if washout - leader > 1.05 and not rebuild_ready:
            conflict_penalty += 0.15 * (washout - leader)
        if franchise < -0.30:
            conflict_penalty += 0.10 + 0.08 * (-franchise)
        if exhausted and branch != "impulse":
            conflict_penalty += 0.08
        if falling_knife:
            conflict_penalty += 0.20

        score = 0.0

        if branch == "impulse":
            score = (
                0.38 * leader
                + 0.18 * franchise
                + 0.14 * stability
                + 0.13 * rebuild
                + 0.10 * income_value
                + 0.07 * washout
            )
            if state == "leader":
                score += 0.18
            elif state == "rebuild":
                score += 0.08
            if deep_pullback and not rebuild_ready:
                score -= 0.16

        elif branch == "rotation":
            score = (
                0.27 * leader
                + 0.24 * rebuild
                + 0.18 * franchise
                + 0.13 * stability
                + 0.10 * income_value
                + 0.08 * washout
            )
            if state == "rebuild":
                score += 0.16
            elif state == "leader":
                score += 0.08
            elif state == "franchise":
                score += 0.05
            if deep_pullback and franchise < 0.0:
                score -= 0.10

        elif branch == "rebuild":
            score = (
                0.31 * rebuild
                + 0.22 * franchise
                + 0.16 * stability
                + 0.13 * income_value
                + 0.10 * leader
                + 0.08 * washout
            )
            if state == "rebuild":
                score += 0.18
            if state == "franchise":
                score += 0.08
            if leader_ready and not deep_pullback:
                score += 0.04

        else:
            score = (
                0.31 * stability
                + 0.24 * franchise
                + 0.18 * income_value
                + 0.14 * rebuild
                + 0.08 * leader
                + 0.05 * washout
            )
            if state == "franchise":
                score += 0.16
            if state == "rebuild" and realized_vol < 32.0:
                score += 0.07
            if large_cap_defense and franchise > 0.0:
                score += 0.05
            if deep_pullback and not rebuild_ready:
                score -= 0.10

        if large_cap_defense and branch != "impulse":
            score += 0.03
        if trading_days < 38.0:
            score -= 0.10

        score -= conflict_penalty
        score += 0.05 * clamp(stability, -0.8, 1.0)

        scores[symbol] = score

    return scores