============================================================
ALGO - DOCUMENT HEADER
------------------------------------------------------------
Doc ID       : B7
Title        : CORE - METRICS SPEC (CORE-ONLY / Fonte di verita' numerica)
Filename     : B7 - CORE - METRICS SPEC (CORE-ONLY) - V06.txt
Version      : V06
Updated      : 2026-04-25 16:35 (Europe/Rome)
Status       : ACTIVE (CORE-ONLY)
Changelog    :
- V06: chiarito che identificatori umani persistiti come `run_seq` / `trade_seq` hanno valore di audit/UI identity e non alterano la numerica CORE delle metriche.
- V05: canonizzate account_size_required / recommended su base realized-path MAE + max_dd_tctc.
- V04: allineato il lessico a EXEC_TF e MRE.
- V04: esplicitato che i trades validati possono provenire da Pattern multi-market sincronizzati via dt.
============================================================

B7 - CORE - METRICS SPEC (CORE-ONLY / Fonte di verita' numerica)
Versione: V06
Status  : ACTIVE (CORE-ONLY)

============================================================
SCOPO
============================================================
- Definire le metriche di performance/rischio calcolate dal CORE ALGO.
- Stabilire la fonte di verita' numerica dopo la validazione B6.

============================================================
PRINCIPIO FONDAMENTALE
============================================================
Tutte le metriche in ALGO:
- sono calcolate DOPO la validazione B6
- usano solo trades validati e metadata canonici
- non dipendono da logica analytics calcolata nell'EA

============================================================
DATI DI INPUT PER LE METRICHE
============================================================
Il CORE usa esclusivamente:
- lista trades validati
- strategy_params.variables.initial_capital
- contract_specs del simbolo quando servono informazioni contrattuali/currency
- timeline dei trades

Regole:
- il timeframe top-level del trade output rappresenta EXEC_TF del run
- eventuali Pattern multi-market sono gia' stati sincronizzati a livello EA/runtime tramite dt
- il CORE non ricostruisce la logica dei Pattern
- eventuali identificatori umani persistiti come `run_seq` o `trade_seq` hanno valore di audit/UI identity e non modificano la numerica CORE delle metriche

============================================================
PNL & COSTI
============================================================
Per ogni trade i:
- pnl_gross_i
- commission_i
- slippage_i
- pnl_net_i

Identity check:
pnl_net_i = pnl_gross_i - commission_i - slippage_i

============================================================
EQUITY CURVE
============================================================
E(0) = initial_capital
E(exit_dt_i) = E(exit_dt_{i-1}) + pnl_net_i

============================================================
HOLDING TIME (CANONICO)
============================================================
Fonte canonica:
- holding time per trade = exit_dt - entry_dt

Regole:
- bars held devono essere calcolati da entry_bar / exit_bar sul dataset EXEC del run
- time held e bars held devono risultare coerenti con EXEC_TF

============================================================
MAE / MFE E CURRENCY GOVERNANCE
============================================================
Misure canoniche in output EA:
- mae_ticks, mfe_ticks
- mae_points, mfe_points
- mae_ccy_1c, mfe_ccy_1c

Regole:
- *_ccy_1c e' sempre per 1 contratto
- eventuali totali di posizione sono derivati dal CORE:
  - *_ccy_total = *_ccy_1c * qty

============================================================
RETURNS, PERFORMANCE E RISCHIO
============================================================
Il CORE calcola in modo deterministico:
- Net Profit
- Gross Profit / Gross Loss
- Profit Factor
- Average Trade
- Win Rate
- Avg Win / Avg Loss
- Expectancy se prevista
- CAGR se definito per il periodo
- periodic average returns quando implementate e versionate:
  - daily
  - weekly
  - monthly
  - yearly
- dispersione trade-level quando implementata e versionata:
  - std dev trade profit
- Max Drawdown
- Drawdown duration
- Sharpe / Sortino / altre metriche se implementate e versionate

============================================================
ACCOUNT SIZE / CAPITAL ADEQUACY
============================================================
Metriche canoniche:
- account_size_required
- account_size_recommended
- return_on_account_required
- return_on_account_recommended

Definizioni:
- per ogni trade i:
  - pnl_before_i = somma dei pnl_net_j per tutti i trade chiusi con j < i
  - mae_total_i = abs(qty_i) * mae_ccy_1c_i
  - capital_required_candidate_i = max(0, mae_total_i - pnl_before_i)
- account_size_required = max(capital_required_candidate_i) su tutti i trade

Interpretazione:
- account_size_required = capitale iniziale minimo necessario per riprodurre il path storico realizzato
  senza che l'open equity vada sotto zero durante la peggiore escursione avversa intratrade.
- la metrica usa il path reale dei trade e le MAE canoniche validate.
- la metrica NON usa il nozionale del contratto e NON usa stime implicite di broker margin.

Buffer raccomandato:
- max_dd_tctc = max drawdown trade-close-to-trade-close
- account_size_recommended = account_size_required + abs(max_dd_tctc)

Returns collegati:
- return_on_account_required = net_profit / account_size_required
- return_on_account_recommended = net_profit / account_size_recommended

Note:
- eventuali metriche di esposizione nozionale o proxy di costo posizione non definiscono account size.
- eventuali metriche broker-margin richiedono contract_specs espliciti dedicati e non vanno inferite.

============================================================
FINE B7
============================================================