============================================================
ALGO - DOCUMENT HEADER
------------------------------------------------------------
Doc ID       : B1
Title        : EA - ALIGNMENT MATRIX (ALL REQUIRED)
Filename     : B1 - EA - ALIGNMENT MATRIX (ALL REQUIRED) - V06.txt
Version      : V06
Updated      : 2026-04-11 22:35 (Europe/Rome)
Status       : READY FOR IMPLEMENTATION
Changelog    :
- V06: aggiornato l'indice canonico fino a B10 e incluso il pacchetto AI esterna.
- V05: riallineato al modello Pattern Source Family / EXEC_TF / MRE.
- V05: introdotta la risoluzione automatica dei tf del Pattern tramite Pattern Source Family.
- V05: aggiornato il contratto input EA da pattern_dfs flat a pattern_contexts per Pattern.
============================================================

B1 - EA - ALIGNMENT MATRIX (ALL REQUIRED)
Versione: V06
Status  : READY FOR IMPLEMENTATION

SCOPO
- Allineare EA, UI, API, runtime, validator, DB ed export.
- Definire cosa deve essere IDENTICO in tutti i layer.

============================================================
1) DECISION REGISTER (HARD-LAW)
============================================================
DR-01 DB WINS
- Il DB e' la source of truth per timeframe canonici, dataset, source family e contract specs.

DR-02 TIMEFRAME TOKENS CANONICI
- Token supportati: S1, M1, M3, M5, M10, M15, M30, H1, H2, H4, H6, D, W, M, Y.
- Daily canonico = D.
- Vietati alias e sinonimi.

DR-03 DATASET != TIMEFRAME
- Il timeframe non identifica da solo il dataset.
- Possono esistere piu' dataset con lo stesso timeframe.

DR-04 PATTERN SOURCE FAMILY
- La scelta dati delle Conditions avviene a livello di Pattern Source Family.
- L'utente non sceglie un dataset singolo di Pattern a tf fisso.
- Il runtime risolve i dataset richiesti da tutte le Conditions del Pattern.

DR-05 EXEC_TF
- EXEC_TF e' il timeframe operativo scelto nel run.
- Entry/Exit usano EXEC.
- MRE definisce il minimo EXEC_TF ammesso.

DR-06 EA INPUT CONTRACT CANONICO
run_backtest(symbol, timeframe, period, params, df_exec, pattern_contexts)
- timeframe = EXEC_TF del run
- df_exec = dataframe del dataset di esecuzione
- pattern_contexts = dict[pattern_id -> pattern context risolto dal runtime]

DR-07 AI_DESCRIPTION
- Nome concettuale: AI_DESCRIPTION
- Chiave output: ai_description

DR-08 ALL REQUIRED / NO EXTRA KEYS
- Ogni chiave prevista dallo schema deve esistere sempre.
- Nessuna chiave extra fuori contratto.

DR-09 DATETIME / TIMEZONE
- Input market data: dt = BAR START in America/New_York.
- Output EA: UTC ISO-8601 con Z.

DR-10 COSTI / MAE-MFE
- commission_per_trade e slippage_ticks sono roundturn per 1 contratto.
- trade.commission e trade.slippage sono totali posizione.
- MAE/MFE canonici: ticks, points, ccy_1c.

============================================================
2) MATRICE DI ALLINEAMENTO END-TO-END
============================================================
2.1 EA
- Dichiara PATTERN_REGISTRY, Variables, Constants, Pattern TF e MRE.
- Produce trades chiusi + events.
- Usa solo timeframe canonici del DB e EXEC come token logico.

2.2 UI BACKTEST
- Permette all'utente di scegliere:
  - exec_symbol
  - exec_tf
  - exec_dataset_id
  - per ogni Pattern: pattern_symbol e pattern_source_family
- Non chiede un dataset Pattern a tf fisso.

2.3 API / BACKEND
- Riceve exec_dataset_id e Pattern Source Family esplicite.
- Valida la coerenza tra source family e tf richiesti dalle Conditions.
- Passa al runtime solo dataframe risolti esplicitamente dal DB.

2.4 RUNTIME / ENGINE
- Carica df_exec dal dataset di esecuzione selezionato.
- Risolve per ogni Pattern i dataset necessari alle sue Conditions.
- Non costruisce timeframe a partire da altri timeframe.

2.5 DB
- datasets = catalogo dataset disponibili.
- prices = serie prezzi legate a dataset_id.
- source family = attributi strutturali che raggruppano i dataset coerenti di un Pattern.
- contract_specs = specifiche contrattuali.

2.6 VALIDATOR / CORE
- B6 valida schema EA e coerenza numerica.
- B7 calcola metriche solo dopo validazione.

============================================================
3) CHECKLIST DI COERENZA
============================================================
- AI_DESCRIPTION / ai_description ovunque.
- Daily canonico D ovunque.
- Nessun alias timeframe.
- Nessun fallback dataset/timeframe.
- Nessuna metriche calcolate nell'EA.
- Variables e Constants separate.
- Pattern TF derivato, non scelto manualmente come dataset singolo.
- EXEC_TF usato come nome canonico del timeframe operativo.

============================================================
4) CHECKLIST IMPLEMENTATIVA
============================================================
B2
- Glossario canonico su Pattern, Condition, Source Family, EXEC_TF, MRE.

B3
- Contratto EA aggiornato a pattern_contexts e strategy_params separati in variables/constants.

B4
- Regole AI/dev aggiornate al nuovo modello.

B5
- Template ufficiale aggiornato a B3-V04.

B6
- Validator da riallineare alla nuova struttura di registry e params.

B7
- Lessico coerente con EXEC_TF e multi-market.

B8
- Master spec AI-ready allineata al nuovo modello.

B9
- Pacchetto operativo canonico da consegnare a una AI DEV esterna.

B10
- Esempi canonici worked-example per sviluppo umano e AI.

============================================================
FINE B1
============================================================