merge origin/main (discovery strumenti downloader) in shape+portfolios

CLAUDE.md

@@ -17,7 +17,9 @@ Progetto di ricerca: riconoscimento pattern frattali per trading algoritmico su
 ## Struttura
 
 ```
-src/data/              → download e caricamento dati (downloader.py)
+src/data/              → download e caricamento dati
+  downloader.py        → download/caricamento parquet (gate: solo strumenti validati)
+  instruments.py       → discovery + validazione strumenti per exchange, registry
 src/fractal/           → indicatori frattali (patterns.py, indicators.py, similarity.py)
 src/backtest/          → engine di backtesting (engine.py)
 src/strategies/        → classe base Strategy ABC + indicatori condivisi
@@ -49,13 +51,15 @@ strategies.yml         → config multi-strategy paper trader
 docs/diary/            → diario di ricerca giornaliero
 docs/specs/            → specifiche di design
 data/raw/              → file .parquet OHLCV (gitignored)
+data/instruments_registry.json → allowlist strumenti validati (gate del downloader)
 ```
 
 ## Comandi
 
 ```bash
 uv sync                                              # installa dipendenze
-uv run python -m src.data.downloader                  # scarica dati storici
+uv run python -m src.data.downloader                  # scarica dati storici (solo strumenti validati)
+uv run python -m src.data.instruments                 # (ri)costruisci il registry strumenti validati
 uv run python scripts/strategies/MR01_bollinger_fade.py        # backtest una strategia (es. fade)
 uv run python scripts/strategies/PR01_pairs_reversion.py       # backtest pairs market-neutral
 uv run python scripts/analysis/strategy_research.py            # ricerca strategie fee-aware OOS
@@ -83,6 +87,27 @@ df = load_data("ETH", "15m")  # carica un asset/timeframe
 Fonte primaria: Cerbero MCP (endpoint `/mcp-deribit/tools/get_historical`).
 Token observer: nel file `secrets/observer.token` del progetto CerberoSuite.
 
+### Strumenti & validazione (gate raccolta dati)
+
+`src/data/instruments.py` scopre e **valida** gli strumenti per ogni exchange
+implementato — **Deribit** e **Hyperliquid** (esclusi Alpaca/stocks e **Bybit**,
+il cui feed testnet è farlocco). Per ogni perpetuo enumera via `get_instruments`
+/`get_markets` e verifica sui **dati storici realmente raccoglibili**:
+esistenza, congruenza OHLC, not-flat (scarta contratti morti), liquidità (volume
+daily) e **congruenza prezzo cross-exchange** (scostamento dalla mediana del
+base-coin ≤ 5% → scarta outlier come `SOL-PERPETUAL`=9.6 vs SOL reale ~82).
+
+Output: `data/instruments_registry.json` (strumenti validi, timeframe, start-date).
+**Gate:** `_download_cerbero_range` rifiuta gli strumenti non validati (override
+`allow_unvalidated=True` solo per casi eccezionali). Rigenera con
+`python -m src.data.instruments`.
+
+> **NB testnet.** Il token Cerbero punta a testnet; la congruenza cross-exchange
+> è il filtro che distingue i feed realistici (Deribit, Hyperliquid) da quelli
+> farlocchi (Bybit). Simboli Deribit: BTC/ETH = `<COIN>-PERPETUAL` (inverse);
+> alt = `<COIN>_USDC-PERPETUAL` (lineari USDC). Registry attuale: Deribit 18/106,
+> Hyperliquid 66/74 validi (major liquidi: BTC dal 2018, alt dal 2022).
+
 ## Strategie attive
 
 > **LEZIONE CRITICA (2026-05-28).** L'intera famiglia squeeze-breakout (SQ01-04,