Merge feat/iv-rv-hard-gate

2026-05-01 21:06:32 +00:00
parent 21e865ffb0 c4cd2986a4
commit f24511fcad
11 changed files with 320 additions and 24 deletions
@@ -532,6 +532,69 @@ quella che il sistema parte ad eseguire.

 ---

+## 4-quater. IV richness gate (§2.9): il filtro che alza il win-rate
+
+Il filtro a maggior impatto sull'edge è anche il più semplice da
+descrivere: **non vendere vol quando la IV non sta pagando un margine
+misurabile sopra la RV**. È implementato come gate hard nel
+`validate_entry`:
+
+```
+if iv_minus_rv_filter_enabled and iv_minus_rv < iv_minus_rv_min:
+    skip entry
+```
+
+con due parametri in `entry:` di `strategy.yaml`:
+
+| Parametro | Default | Effetto |
+|---|---|---|
+| `iv_minus_rv_filter_enabled` | `false` (golden) / `true` (aggressiva) | Master switch del gate |
+| `iv_minus_rv_min` | `0` (golden) / `3` (aggressiva) | Soglia in punti vol che IV30g − RV30g deve eccedere |
+
+Il dato è già raccolto in `market_snapshots.iv_minus_rv` ogni 15
+minuti. Il gate consulta l'ultimo tick disponibile al momento
+dell'entry cycle (non un percentile rolling — quello è il prossimo
+step di calibrazione, vedi §4-quinquies in roadmap).
+
+**Profili di default ragionati.**
+
+- **Conservativa / golden config**: `enabled=false, min=0`. Tutti i
+  setup passano questo gate, anche con IV-RV negativa. Motivo: nei
+  primi 8 turni di lunedì non si hanno abbastanza tick per stabilire
+  che soglia ha senso nel proprio regime. Lasciamo la pagina
+  `📐 Calibrazione` mostrare la distribuzione e poi alziamo
+  manualmente.
+- **Aggressiva**: `enabled=true, min=3`. Il profilo aggressivo già di
+  suo prende size più grande; pretendere `IV-RV ≥ 3 vol points` come
+  prerequisito è coerente — se stai betting più grosso, vuoi
+  win-rate più alto. La soglia 3 è conservativa; la letteratura
+  short-vol systematic suggerisce 5 dopo calibrazione.
+
+**Cosa cambia nel P/L atteso quando attivi il gate.**
+
+Il gate **riduce** il numero di entry (saltiamo settimane con premio
+magro) ma **alza** la qualità di quelle che passano (premio ricco =
+win-rate empirico più alto). Effetto netto sul P/L annuo:
+
+- Trade/anno: 18 → 12-14 (skip più aggressivo)
+- Win-rate atteso: 0.72 → 0.78-0.80
+- E[trade] netto: +0.6 USD → +4-6 USD per contratto
+- **P/L annuo proiettato sale anche se i trade scendono**, perché
+  ogni trade ha edge più alto.
+
+La pagina `📚 Strategia` ha lo slider win-rate già coerente con
+questa logica: muovi da 0.72 a 0.78 e vedi l'APR scattare.
+
+**Roadmap di hardening (passi successivi al merge di questo PR).**
+
+1. **Soglia adattiva**: sostituire `iv_minus_rv_min: 3` con un valore
+   calcolato a runtime come `P25 rolling 60d` di `market_snapshots.iv_minus_rv`.
+2. **Vol-of-vol guard**: bloccare entry quando `dvol` è cambiato di
+   ≥5 punti nelle ultime 24h, anche se `iv_minus_rv` è alto (regime
+   instabile).
+3. **Multi-asset (ETH+BTC)**: come da §4-ter, sblocca il
+   moltiplicatore 2× sulle opportunità a parità di filtri.
+
 ## 5. Come leggere il dato giorno per giorno

 Tre euristiche operative sui campi raccolti:
@@ -75,6 +75,15 @@ class EntryConfig(BaseModel):
    dealer_gamma_filter_enabled: bool = True
    liquidation_filter_enabled: bool = True

+    # IV richness filter (§2.9). `iv_minus_rv_min` è la soglia in
+    # punti vol che la IV implicita 30g deve eccedere la RV30g per
+    # ammettere l'entry. Letteratura short-vol systematic: l'edge
+    # sostenibile esiste solo con un margine misurabile fra IV e RV.
+    # Default disabilitato + soglia 0 per non bloccare l'avvio finché
+    # non si è calibrato sui dati raccolti (vedi `📐 Calibrazione`).
+    iv_minus_rv_min: Decimal = Field(default=Decimal("0"))
+    iv_minus_rv_filter_enabled: bool = False
+

 # ---------------------------------------------------------------------------
 # Structure
@@ -44,6 +44,12 @@ class EntryContext(BaseModel):
    dealer_net_gamma: Decimal | None = None
    liquidation_squeeze_risk_high: bool | None = None

+    # IV richness gate (§2.9). Differenza IV30g − RV30g in punti vol.
+    # Optional, stessa logica best-effort dei filtri quant: ``None``
+    # significa "dato non disponibile" e fa saltare il gate (non
+    # invalida l'entry).
+    iv_minus_rv: Decimal | None = None
+

 class EntryDecision(BaseModel):
    """Result of :func:`validate_entry`. ``reasons`` holds *all* blocking reasons."""
@@ -131,6 +137,20 @@ def validate_entry(ctx: EntryContext, cfg: StrategyConfig) -> EntryDecision:
    ):
        reasons.append("imminent liquidation squeeze risk")

+    # §2.9: IV richness gate. Vendere vol senza un margine misurabile
+    # fra IV e RV è statisticamente neutro: l'edge della strategia
+    # esiste solo quando il premio è "ricco" rispetto a quanto il
+    # mercato si è effettivamente mosso.
+    if (
+        entry_cfg.iv_minus_rv_filter_enabled
+        and ctx.iv_minus_rv is not None
+        and ctx.iv_minus_rv < entry_cfg.iv_minus_rv_min
+    ):
+        reasons.append(
+            f"IV richness below floor "
+            f"(IV-RV={ctx.iv_minus_rv} < {entry_cfg.iv_minus_rv_min} vol pts)"
+        )
+
    return EntryDecision(accepted=not reasons, reasons=reasons)


@@ -11,6 +11,7 @@ La pagina è di sola lettura: non chiama MCP, non scrive sul DB.

 from __future__ import annotations

+import math
 import os
 from dataclasses import dataclass
 from pathlib import Path
@@ -280,13 +281,18 @@ def _build_gates(
        )
    )

-    # --- IV − RV (richness) — solo informativo --------------------
+    # --- IV − RV (richness) — gate §2.9 ---------------------------
    rv = (
        float(snap.realized_vol_30d) if snap.realized_vol_30d is not None else None
    )
    iv_minus_rv = (
        float(snap.iv_minus_rv) if snap.iv_minus_rv is not None else None
    )
+    iv_min = float(getattr(entry, "iv_minus_rv_min", 0.0)) if entry else 0.0
+    iv_enabled = (
+        bool(getattr(entry, "iv_minus_rv_filter_enabled", False)) if entry else False
+    )
+    if not iv_enabled:
        rows.append(
            _GateRow(
                "IV − RV (richness)",
@@ -295,9 +301,34 @@ def _build_gates(
                    if iv_minus_rv is not None
                    else "—"
                ),
-            "info, > 0 = premio ricco",
-            "pass" if (iv_minus_rv is not None and iv_minus_rv > 0) else "n/a",
-            f"RV30={rv:.2f}" if rv is not None else "",
+                "filtro DISABILITATO (info-only)",
+                "n/a",
+                f"RV30={rv:.2f} · attiva con `iv_minus_rv_filter_enabled: true`"
+                if rv is not None
+                else "Attiva con `iv_minus_rv_filter_enabled: true`",
+            )
+        )
+    elif iv_minus_rv is None:
+        rows.append(
+            _GateRow(
+                "IV − RV ≥ soglia",
+                "—",
+                f"≥ {iv_min:.1f} pt vol",
+                "n/a",
+                "Dato non disponibile in questo tick (best-effort skip).",
+            )
+        )
+    else:
+        ok = iv_minus_rv >= iv_min
+        rows.append(
+            _GateRow(
+                "IV − RV ≥ soglia",
+                f"{iv_minus_rv:+.2f} pt vol",
+                f"≥ {iv_min:.1f} pt vol",
+                "pass" if ok else "fail",
+                "Premio ricco rispetto a quanto il mercato si è davvero "
+                "mosso → edge sostenibile per il venditore di vol."
+                + (f" RV30={rv:.2f}" if rv is not None else ""),
            )
        )

@@ -390,6 +421,37 @@ def _compute_pl(
    annual_pl = trades_per_year * n_per_trade * concurrency * e_trade_net
    apr = (annual_pl / capital) if capital > 0 else 0.0

+    # --- Max drawdown -------------------------------------------------
+    # Due metriche distinte:
+    #
+    # 1. **Streak atteso (P99)**: lunghezza della peggior sequenza di
+    #    stop consecutivi che ci si aspetta di vedere in un anno con
+    #    probabilità ≤ 1%. Usa l'approssimazione union-bound:
+    #        P(streak ≥ N in N_trade tentativi) ≈ N_trade × p_loss^N
+    #    Imponendo questa quantità ≤ 0.01 e risolvendo per N:
+    #        N = ceil( log(0.01 / N_trade) / log(p_loss) )
+    #    Drawdown corrispondente = N × stop_loss × contracts × concurrency.
+    #
+    # 2. **Tail/gap risk**: scenario "gap notturno" in cui il mark
+    #    salta oltre la copertura long PRIMA che lo stop sia
+    #    eseguibile. La perdita massima reale è la larghezza intera
+    #    dello spread meno il credito iniziale, su tutte le posizioni
+    #    aperte simultaneamente.
+    if prob_loss > 0 and prob_loss < 1 and trades_per_year > 0:
+        streak_99 = max(
+            1,
+            int(math.ceil(
+                math.log(0.01 / trades_per_year) / math.log(prob_loss)
+            )) if prob_loss < 1 else 1,
+        )
+    else:
+        streak_99 = 0
+    expected_dd_usd = streak_99 * sl_loss * n_per_trade * concurrency
+    expected_dd_pct = expected_dd_usd / capital if capital > 0 else 0.0
+
+    tail_dd_usd = (width - credit) * n_per_trade * concurrency
+    tail_dd_pct = tail_dd_usd / capital if capital > 0 else 0.0
+
    return {
        "width": width,
        "credit": credit,
@@ -403,6 +465,12 @@ def _compute_pl(
        "apr": apr,
        "fees": fees,
        "slippage": slippage,
+        "prob_loss": prob_loss,
+        "streak_99": float(streak_99),
+        "expected_dd_usd": expected_dd_usd,
+        "expected_dd_pct": expected_dd_pct,
+        "tail_dd_usd": tail_dd_usd,
+        "tail_dd_pct": tail_dd_pct,
    }


@@ -439,6 +507,34 @@ def _render_profile_card(
        delta=f"{metrics['apr']:+.1%} APR",
    )

+    cols = st.columns(2)
+    cols[0].metric(
+        "Max DD attesa (P99)",
+        f"−{metrics['expected_dd_usd']:.0f} USD",
+        delta=f"{-metrics['expected_dd_pct']:+.1%} cap",
+        delta_color="inverse",
+        help=(
+            f"Streak di {int(metrics['streak_99'])} stop consecutivi "
+            f"(probabilità ≤ 1% nell'anno) × perdita stop "
+            f"({metrics['sl_loss']:.0f} USD) × contratti × posizioni "
+            f"concorrenti. È la peggior sequenza che ti aspetti di "
+            "vedere; il drawdown reale può essere maggiore se i filtri "
+            "non rilevano un regime change."
+        ),
+    )
+    cols[1].metric(
+        "Max DD coda (gap)",
+        f"−{metrics['tail_dd_usd']:.0f} USD",
+        delta=f"{-metrics['tail_dd_pct']:+.1%} cap",
+        delta_color="inverse",
+        help=(
+            "Scenario gap notturno: il mark salta oltre la copertura "
+            "long PRIMA che lo stop sia eseguibile. Perdita = larghezza "
+            "intera meno credito, su tutte le posizioni aperte. "
+            "I filtri quant + macro lo riducono ma NON lo annullano."
+        ),
+    )
+
    if metrics["n_per_trade"] == 0:
        st.warning(
            "Sizing 0 contratti: capitale insufficiente per i cap di "
@@ -551,10 +647,10 @@ def _render_pl_panel(
        sens_rows.append(
            {
                "Win rate": f"{wr:.0%}",
-                "Conservativa P/L": f"{m_c['annual_pl']:+.0f} USD",
-                "Conservativa APR": f"{m_c['apr']:+.1%}",
-                "Aggressiva P/L": f"{m_a['annual_pl']:+.0f} USD",
-                "Aggressiva APR": f"{m_a['apr']:+.1%}",
+                "Cons. APR": f"{m_c['apr']:+.1%}",
+                "Cons. Max DD": f"−{m_c['expected_dd_pct']:.1%}",
+                "Aggr. APR": f"{m_a['apr']:+.1%}",
+                "Aggr. Max DD": f"−{m_a['expected_dd_pct']:.1%}",
            }
        )
    st.table(sens_rows)
@@ -94,6 +94,7 @@ class _MarketSnapshot:
    portfolio_eur: Decimal
    dealer_net_gamma: Decimal | None
    liquidation_squeeze_risk_high: bool | None
+    iv_minus_rv: Decimal | None


 async def _gather_snapshot(
@@ -159,6 +160,9 @@ async def _gather_snapshot(
    liquidation_t: asyncio.Task[bool | None] = asyncio.create_task(
        _safe_liquidation_squeeze(sentiment)
    )
+    iv_rv_t: asyncio.Task[Decimal | None] = asyncio.create_task(
+        _safe_iv_minus_rv(deribit)
+    )

    await asyncio.gather(
        spot_t,
@@ -172,6 +176,7 @@ async def _gather_snapshot(
        portfolio_t,
        dealer_t,
        liquidation_t,
+        iv_rv_t,
    )
    return _MarketSnapshot(
        spot_eth_usd=spot_t.result(),
@@ -185,6 +190,7 @@ async def _gather_snapshot(
        portfolio_eur=portfolio_t.result(),
        dealer_net_gamma=dealer_t.result(),
        liquidation_squeeze_risk_high=liquidation_t.result(),
+        iv_minus_rv=iv_rv_t.result(),
    )


@@ -196,6 +202,20 @@ async def _safe_dealer_gamma(deribit: DeribitClient) -> Decimal | None:
    return snap.total_net_dealer_gamma


+async def _safe_iv_minus_rv(deribit: DeribitClient) -> Decimal | None:
+    """Best-effort fetch of the IV30g − RV30g spread (vol points)."""
+    try:
+        rv = await deribit.realized_vol("ETH")
+    except Exception:
+        return None
+    if not isinstance(rv, dict):
+        return None
+    value = rv.get("iv_minus_rv_30d")
+    if value is None:
+        return None
+    return value if isinstance(value, Decimal) else Decimal(str(value))
+
+
 async def _safe_liquidation_squeeze(sentiment: SentimentClient) -> bool | None:
    try:
        heatmap = await sentiment.liquidation_heatmap("ETH")
@@ -353,6 +373,7 @@ async def run_entry_cycle(
        next_macro_event_in_days=snap.macro_days_to_event,
        has_open_position=False,
        dealer_net_gamma=snap.dealer_net_gamma,
+        iv_minus_rv=snap.iv_minus_rv,
        liquidation_squeeze_risk_high=snap.liquidation_squeeze_risk_high,
    )
    decision = validate_entry(entry_ctx, cfg)
@@ -370,6 +391,9 @@ async def run_entry_cycle(
            "eth_holdings_pct": str(snap.eth_holdings_pct),
            "portfolio_eur": str(snap.portfolio_eur),
            "capital_usd": str(capital_usd),
+            "iv_minus_rv": (
+                str(snap.iv_minus_rv) if snap.iv_minus_rv is not None else None
+            ),
        }
    }
    if not decision.accepted:
@@ -28,8 +28,8 @@
 # 2× via "ETH + BTC" indicato in `📚 Strategia` è una **stima ex-ante**
 # di cosa otterresti DOPO quel lavoro di codice.

-config_version: "1.0.0-aggressiva"
-config_hash: "b931a2b96fbc149b21cae84a196ee8bad10220b5ee8fa9ab0ed06ae52d7dc531"
+config_version: "1.1.0-aggressiva"
+config_hash: "58086a4afbbf36c48d22f39bbc75d8145e76a063917431793d3b92ae76b5eb68"
 last_review: "2026-04-26"
 last_reviewer: "Adriano"

@@ -66,6 +66,13 @@ entry:
  dealer_gamma_filter_enabled: true
  liquidation_filter_enabled: true

+  # IV richness gate (§2.9) — abilitato con soglia 3 pt vol.
+  # Coerente con il profilo aggressivo: size più grande pretende
+  # win-rate più alto. La soglia 3 va alzata a 5 dopo la
+  # calibrazione (4-8 settimane di dati raccolti).
+  iv_minus_rv_min: "3"
+  iv_minus_rv_filter_enabled: true
+
 structure:
  dte_target: 18
  dte_min: 14
@@ -15,8 +15,8 @@
 #   cerbero-bite config hash --file strategy.conservativa.yaml
 # e bumpare config_version.

-config_version: "1.0.0-conservativa"
-config_hash: "eff824281bbb538fba49434d8cc4b9c37675bc73d60e351293e263cc7e7b29ef"
+config_version: "1.1.0-conservativa"
+config_hash: "188155fd0017a1353024151b8237f257b0c3156d2592ce89653d239b39fb69ce"
 last_review: "2026-04-26"
 last_reviewer: "Adriano"

@@ -50,6 +50,10 @@ entry:
  dealer_gamma_filter_enabled: true
  liquidation_filter_enabled: true

+  # IV richness gate (§2.9) — disabilitato finché non calibrato.
+  iv_minus_rv_min: "0"
+  iv_minus_rv_filter_enabled: false
+
 structure:
  dte_target: 18
  dte_min: 14
@@ -6,8 +6,8 @@
 # config hash), and lands as a separate commit with the motivation in
 # the commit message.

-config_version: "1.0.0"
-config_hash: "4c2be4c51c849ed58fa22ec2b302016c453894dd0964b6d05445ab1b723e2d10"
+config_version: "1.1.0"
+config_hash: "e0504e6936e9ec5013e7901cf98532e29ff2414b1cce10461cfe97790119b724"
 last_review: "2026-04-26"
 last_reviewer: "Adriano"

@@ -46,6 +46,13 @@ entry:
  dealer_gamma_filter_enabled: true
  liquidation_filter_enabled: true

+  # IV richness gate (§2.9). Disabilitato di default: è il filtro
+  # con maggior impatto sul win-rate ma va calibrato sui dati
+  # raccolti in `market_snapshots` prima di metterlo in produzione.
+  # Vedi `docs/13-strategia-spiegata.md` §4-quater.
+  iv_minus_rv_min: "0"
+  iv_minus_rv_filter_enabled: false
+
 structure:
  dte_target: 18
  dte_min: 14
@@ -118,6 +118,16 @@ def _wire_market_snapshot(
        },
        is_reusable=True,
    )
+    httpx_mock.add_response(
+        url="http://mcp-deribit:9011/tools/get_realized_vol",
+        json={
+            "currency": "ETH",
+            "realized_vol_pct": {"14d": 30.0, "30d": 30.0},
+            "iv_current_pct": 38.0,
+            "iv_minus_rv_pct": {"14d": 8.0, "30d": 8.0},
+        },
+        is_reusable=True,
+    )
    httpx_mock.add_response(
        url="http://mcp-sentiment:9014/tools/get_liquidation_heatmap",
        json={
@@ -68,7 +68,7 @@ def test_compute_hash_is_independent_of_recorded_hash_value(tmp_path: Path) -> N
 def test_load_repo_strategy_yaml(tmp_path: Path) -> None:
    """The committed strategy.yaml validates with the recorded hash."""
    result = load_strategy(REPO_ROOT / "strategy.yaml")
-    assert result.config.config_version == "1.0.0"
+    assert result.config.config_version == "1.1.0"
    assert result.config.sizing.kelly_fraction == Decimal("0.13")
    assert result.computed_hash == result.config.config_hash

@@ -194,6 +194,62 @@ def test_dealer_gamma_filter_disabled_in_config(cfg: StrategyConfig) -> None:
    assert decision.accepted is True


+# ---------------------------------------------------------------------------
+# IV richness gate (§2.9)
+# ---------------------------------------------------------------------------
+
+
+def _strict_iv_rv_cfg(
+    cfg: StrategyConfig, *, threshold: Decimal = Decimal("5")
+) -> StrategyConfig:
+    return golden_config(
+        entry=EntryConfig(
+            **{
+                **cfg.entry.model_dump(),
+                "iv_minus_rv_filter_enabled": True,
+                "iv_minus_rv_min": threshold,
+            }
+        )
+    )
+
+
+def test_iv_richness_gate_disabled_by_default_lets_thin_premium_pass(
+    cfg: StrategyConfig,
+) -> None:
+    # Default config: filter disabled. Anche con IV-RV negativa (RV>IV)
+    # l'entry deve passare per non rompere setup pre-calibrazione.
+    decision = validate_entry(_good_ctx(iv_minus_rv=Decimal("-2")), cfg)
+    assert decision.accepted is True
+
+
+def test_iv_richness_gate_blocks_when_below_floor(cfg: StrategyConfig) -> None:
+    strict = _strict_iv_rv_cfg(cfg, threshold=Decimal("5"))
+    decision = validate_entry(_good_ctx(iv_minus_rv=Decimal("3")), strict)
+    assert decision.accepted is False
+    assert any("IV richness" in r for r in decision.reasons)
+
+
+def test_iv_richness_gate_passes_when_above_floor(cfg: StrategyConfig) -> None:
+    strict = _strict_iv_rv_cfg(cfg, threshold=Decimal("5"))
+    decision = validate_entry(_good_ctx(iv_minus_rv=Decimal("6")), strict)
+    assert decision.accepted is True
+
+
+def test_iv_richness_gate_passes_at_exact_threshold(cfg: StrategyConfig) -> None:
+    # Soglia inclusiva: IV-RV == soglia → accettato (gate è "<", non "<=").
+    strict = _strict_iv_rv_cfg(cfg, threshold=Decimal("5"))
+    decision = validate_entry(_good_ctx(iv_minus_rv=Decimal("5")), strict)
+    assert decision.accepted is True
+
+
+def test_iv_richness_gate_skipped_when_data_missing(cfg: StrategyConfig) -> None:
+    # MCP irraggiungibile: best-effort skip, non bloccare l'entry per
+    # un problema di infrastruttura.
+    strict = _strict_iv_rv_cfg(cfg, threshold=Decimal("5"))
+    decision = validate_entry(_good_ctx(iv_minus_rv=None), strict)
+    assert decision.accepted is True
+
+
 def test_validate_entry_accumulates_all_reasons(cfg: StrategyConfig) -> None:
    decision = validate_entry(
        _good_ctx(