feat(live): allerta sul salto di equity — conferma il versamento, segnala un prelievo

La verifica "il cap si adegua?" esisteva solo come sorveglianza di sessione, e il
versamento slitta di giorni: una verifica che vive in una chat non e' una verifica. Resa
permanente e generalizzata.

`write_equity_watermark` ora ritorna {prev, new, pct} quando il salto fra due letture
consecutive supera EQUITY_JUMP_ALERT = 10%; `book_report` lo espone come `equity_jump` e
`book_execute` manda un Telegram con il NUOVO DIMENSIONAMENTO accanto (cap/asset, nozionale
lordo, leva), cosi' il messaggio si legge senza aprire il repo.

Il book ha vol ~0.4%/giorno: un salto del 10% fra due giri orari non puo' venire dal
trading. Quindi l'allerta copre DUE casi con un meccanismo solo:
  - VERSAMENTO: conferma che e' atterrato e che il sizing lo ha seguito;
  - USCITA DI FONDI: un prelievo che non hai chiesto, o una perdita anomala. E' questo il
    caso che conta di piu', ed e' il motivo per cui la soglia e' a due code.

Prima lettura in assoluto -> nessun allarme (senza un "prima" non c'e' un salto).
Il watermark si aggiorna ANCHE quando allerta, o il cap resterebbe indietro (test cablato).

411 test verdi (+7). Strategia, pesi, cron, config INVARIATI.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

scripts/live/book_execute.py

@@ -155,6 +155,22 @@ def _run():
         if do_execute:                            # solo diagnostica: l'hard-cap $/asset limita il downside
             notify("⚠️ BOOK LIVE — equity fallback (sizing su paper_cap)", {"nota": r["eq_fallback"]})
 
+    # Salto di equity: un versamento (conferma che il sizing lo ha seguito) oppure un movimento
+    # NON richiesto (prelievo, perdita anomala). In entrambi i casi va detto subito, e con il
+    # nuovo dimensionamento accanto, cosi' il messaggio si legge senza aprire il repo.
+    jump = r.get("equity_jump")
+    if jump:
+        verso = "VERSAMENTO" if jump["pct"] > 0 else "USCITA DI FONDI"
+        lordo = 2 * r["cap_per_asset"]
+        notify(f"💰 BOOK LIVE — {verso} rilevato ({jump['pct']:+.1%})", {
+            "equity prima": f"${jump['prev']:,.2f}",
+            "equity ora": f"${jump['new']:,.2f}",
+            "cap/asset ora": f"${r['cap_per_asset']:,.2f}",
+            "nozionale lordo max": f"${lordo:,.2f} = leva {lordo/jump['new']:.2f}x",
+        })
+        print(f"  💰 {verso}: ${jump['prev']:,.2f} -> ${jump['new']:,.2f} "
+              f"({jump['pct']:+.1%}) · cap/asset ora ${r['cap_per_asset']:,.2f}")
+
     trader = DeribitTrader() if do_execute else None
     actions = []
     for a in r["assets"]:

src/live/book.py

@@ -73,16 +73,35 @@ def _read_watermark() -> float | None:
         return None
 
 
-def write_equity_watermark(real_equity: float | None) -> None:
-    """Registra l'equity reale ogni volta che e' leggibile. Chiamata da `book_report`."""
+# Variazione di equity fra due letture consecutive oltre la quale si avvisa. Il book ha vol
+# giornaliera ~0.4%: un salto del 10% fra due giri orari non puo' venire dal trading, quindi e'
+# un deposito, un prelievo, o qualcosa che va guardato SUBITO.
+EQUITY_JUMP_ALERT = 0.10
+
+
+def write_equity_watermark(real_equity: float | None) -> dict | None:
+    """Registra l'equity reale ogni volta che e' leggibile. Chiamata da `book_report`.
+
+    Ritorna un dict {prev, new, pct} se il salto rispetto alla lettura precedente supera
+    `EQUITY_JUMP_ALERT`, altrimenti None. Serve a due cose in una: **confermare** che un
+    versamento e' atterrato e che il sizing lo ha seguito, e **segnalare** un movimento che
+    l'operatore non ha causato (prelievo non richiesto, perdita anomala).
+    """
     if real_equity is None or real_equity <= 0:
-        return
+        return None
+    prev = _read_watermark()
     try:
         EQUITY_WATERMARK.parent.mkdir(parents=True, exist_ok=True)
         EQUITY_WATERMARK.write_text(json.dumps(
             {"real_equity": float(real_equity), "ts": pd.Timestamp.now(tz="UTC").isoformat()}))
     except Exception:
         pass                      # il watermark e' un'ottimizzazione di sicurezza, non un requisito
+    if prev is None or prev <= 0:
+        return None               # prima lettura in assoluto: non c'e' un "prima" da confrontare
+    pct = (float(real_equity) - prev) / prev
+    if abs(pct) < EQUITY_JUMP_ALERT:
+        return None
+    return {"prev": prev, "new": float(real_equity), "pct": pct}
 
 
 def _cap(equity: float | None = None, real_equity: float | None = None,
@@ -171,7 +190,7 @@ def book_report(offline: bool = False, equity_override: float | None = None,
     equity = sh["equity"]
     # registra l'equity reale quando e' leggibile: e' cio' che rende sicuro il cap di
     # fallback in OGNI ordine di eventi (vedi _cap).
-    write_equity_watermark(sh.get("real_equity"))
+    equity_jump = write_equity_watermark(sh.get("real_equity"))
     cap = _cap(equity=equity, real_equity=sh.get("real_equity"), eq_fallback=sh.get("eq_fallback"))
     load5m = None
     feed_ages: dict[str, float | None] = {}
@@ -219,6 +238,10 @@ def book_report(offline: bool = False, equity_override: float | None = None,
         cap_per_asset=cap, weights=dict(TP01=W_TP01, SKH01=W_SKH),
         assets=assets, orders=orders, skh_error=skh_error, pos_error=sh.get("pos_error"),
         eq_fallback=sh.get("eq_fallback"),
+        # Salto di equity fra due letture consecutive oltre EQUITY_JUMP_ALERT: dict o None.
+        # Conferma un versamento (e che il sizing lo ha seguito) E segnala un movimento non
+        # richiesto. Il book ha vol ~0.4%/g: un salto del 10% fra due giri orari non e' trading.
+        equity_jump=equity_jump,
         # eta' (minuti) del feed 5m REALMENTE usato per il segnale SKH: None se non misurata
         # (live_feed=False) o non interpretabile. Vale il MASSIMO fra gli asset: se anche uno solo
         # e' stantio, il segnale netto e' sospetto.

tests/test_cap_watermark.py

@@ -118,3 +118,48 @@ def test_la_frazione_di_config_tiene_la_leva_a_1x():
     """2 asset x frac <= 1.0: e' l'ipotesi su cui poggia 'la liquidation fee non ci tocca' (26/07)."""
     cfg = json.loads((ROOT / "config" / "live.json").read_text())
     assert float(cfg["max_notional_per_asset_frac"]) * 2 <= 1.0
+
+
+# ===========================================================================
+# allerta sul SALTO di equity — conferma un versamento, segnala un prelievo
+# ===========================================================================
+def test_nessun_allarme_su_variazione_normale(wm):
+    B.write_equity_watermark(600.0)
+    assert B.write_equity_watermark(605.0) is None, "una variazione da trading non deve allertare"
+
+
+def test_un_versamento_produce_l_allarme_col_segno_giusto(wm):
+    B.write_equity_watermark(596.92)
+    j = B.write_equity_watermark(6047.0)
+    assert j is not None
+    assert j["prev"] == pytest.approx(596.92) and j["new"] == pytest.approx(6047.0)
+    assert j["pct"] > 0
+
+
+def test_un_prelievo_non_richiesto_produce_l_allarme(wm):
+    """Il caso che conta piu' del versamento: fondi che escono senza che tu li abbia chiesti."""
+    B.write_equity_watermark(6047.0)
+    j = B.write_equity_watermark(3000.0)
+    assert j is not None and j["pct"] < -B.EQUITY_JUMP_ALERT
+
+
+def test_la_prima_lettura_in_assoluto_non_allerta(wm):
+    """Senza un 'prima' non c'e' un salto: allertare al primo avvio sarebbe rumore."""
+    assert B.write_equity_watermark(6047.0) is None
+
+
+def test_il_watermark_si_aggiorna_anche_quando_allerta(wm):
+    """L'allarme non deve impedire l'aggiornamento, o il cap resterebbe indietro."""
+    B.write_equity_watermark(596.92)
+    B.write_equity_watermark(6047.0)
+    assert B._read_watermark() == pytest.approx(6047.0)
+    assert B._cap(equity=6047.0, real_equity=6047.0, eq_fallback=None) == pytest.approx(3023.5)
+
+
+def test_la_soglia_di_salto_e_congelata():
+    assert B.EQUITY_JUMP_ALERT == 0.10
+
+
+def test_book_execute_avvisa_sul_salto():
+    src = (ROOT / "scripts" / "live" / "book_execute.py").read_text()
+    assert "equity_jump" in src and "VERSAMENTO" in src