cblib causale: spot +1h e DVOL +1 giorno (debito §5.18); §11 rimisurato 0,714 → 0,712, verdetti invariati

- cblib.causale(s, cadenza): spot_series e dvol_series escono causali (asof = ultima chiusura NOTA);
  il DVOL giornaliero era una seconda serie con lo stesso difetto (fino a 24h avanti), verificato contro
  l'API pubblica a 1h. Regolamento ST alle 08:00 invece delle 09:00.
- §11 riprodotto al millesimo su worktree HEAD (0,714 [0,690-0,779], n=19, flag --al) e rimisurato:
  0,712 [0,664-0,732]; solo spot 0,721, solo DVOL 0,693, DVOL orario di controllo 0,717. Mediana onesta
  BTC 1,45 → 2,12, fee 1,51x/1,87x. r0730: 0,73 → 0,71. §75: ETH pre 0,76, BTC durante 0,89 (orario 0,83).
  skew panel ≤0,005. vrp_f_watch: f canonico 0,732 → 0,706, differenza +0,097 [+0,042, +0,140].
- r0909 senza doppio shift, contesto sul DVOL del giorno; r0822 regime su date di calendario; r0901
  join riallineato (bit-exact). Aperti con costo: DVOL orario (−0,04/+0,06 nel crollo), spot 5m (≤25 min).
- test: +3 causalita' in test_cb_chain_vrp, anti-doppio-shift in test_r0909; suite 1011/1011.
- revisione fable: 16 segnalazioni, tutte applicate (fra cui un «−1,8% in un'ora» che era +3,9%).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bjj5vPEBoAJrB23P6RjKzs

scripts/research/cblib.py

@@ -13,6 +13,10 @@ Regola che vale per ogni misura fatta con questo modulo: il f della sola gamba c
 dello spread. Il modello sbaglia soprattutto sull'ala che si COMPRA (piu' OTM, IV piu' alta per
 skew, prezzata dal modello a vol ATM) -> misurare una gamba sola da' la risposta sbagliata con
 segno rassicurante.
+
+Seconda regola (09/09, debito §5.18): spot e DVOL escono da qui gia' CAUSALI — `asof(ts)` da'
+l'ultima chiusura nota a ts. Chi costruisce una serie di prezzi altrove usi `causale()`, non
+l'indice del feed com'e' (etichettato all'apertura: D6).
 """
 from __future__ import annotations
 
@@ -65,23 +69,48 @@ def puts(asset: str, df: pd.DataFrame | None = None) -> pd.DataFrame:
     return d[(d["asset"] == asset) & (d["option_type"] == "P")]
 
 
+def causale(s: pd.Series, cadenza: str) -> pd.Series:
+    """Rietichetta una serie di CHIUSURE dall'APERTURA della barra all'istante in cui la chiusura
+    e' nota (apertura + cadenza), cosi' `s.asof(ts)` restituisce l'ultima chiusura CONOSCIUTA a ts
+    e mai una futura. I valori non si toccano, solo le etichette.
+
+    🚨 Perche' esiste (debito §5.18, 09/09): i feed del progetto sono etichettati all'apertura —
+    la barra 1h `20:00` chiude col 5m delle 20:55 (verificato: chiusura 1h a T == chiusura 5m a
+    T+55 nel 100% delle barre) e la riga DVOL del giorno D e' la chiusura delle 23:00 di D
+    (verificato contro la risoluzione 1h dell'API pubblica). Senza questo spostamento `asof(ts)`
+    dava lo spot di UN'ORA dopo e il DVOL di FINO A 24 ORE dopo l'ingresso (D6, quinta occorrenza)."""
+    out = s.copy()
+    out.index = out.index + pd.Timedelta(cadenza)
+    return out
+
+
 @lru_cache(maxsize=8)
 def spot_series(asset: str) -> pd.Series:
+    """Chiusure 1h del feed certificato, etichettate all'istante in cui sono NOTE (apertura + 1h).
+
+    `spot_series(a).asof(ts)` = ultima chiusura oraria conosciuta a `ts`. Conseguenza sul
+    regolamento: `asof(exp)` alle 08:00 e' la chiusura della barra 07:00, cioe' il prezzo delle
+    08:00 — prima era il prezzo delle 09:00, un'ora DOPO la scadenza."""
     from scripts.analysis.research_lab import load_tf
     px = load_tf(asset, "1h")
     s = pd.Series(px["close"].values.astype(float),
                   index=pd.to_datetime(px["timestamp"], unit="ms", utc=True)).sort_index()
     s.index = pd.DatetimeIndex(s.index).as_unit("ns")   # le quote bite hanno microsecondi
-    return s
+    return causale(s, "1h")
 
 
 @lru_cache(maxsize=8)
 def dvol_series(asset: str) -> pd.Series:
+    """DVOL giornaliero (chiusura), etichettato all'istante in cui e' NOTO (giorno + 1D).
+
+    `dvol_series(a).asof(ts)` = ultima chiusura giornaliera del DVOL conosciuta a `ts`: dentro il
+    giorno D e' la chiusura di D−1, quindi vecchia fino a 23 ore. E' il prezzo della causalita'
+    con un feed giornaliero; l'alternativa (DVOL orario dall'API pubblica) non e' nel feed."""
     d = pd.read_parquet(RAW / f"dvol_{asset.lower()}.parquet")
     s = pd.Series(d["close"].values.astype(float),
                   index=pd.to_datetime(d["timestamp"], unit="ms", utc=True)).sort_index()
     s.index = pd.DatetimeIndex(s.index).as_unit("ns")
-    return s
+    return causale(s, "1D")
 
 
 # ------------------------------------------------------------------ prezzo