============================================================
ALGO - DOCUMENT HEADER
------------------------------------------------------------
Doc ID       : B4
Title        : EA - AI PROMPT & DEV RULES (CANONICAL)
Filename     : B4 - EA - AI PROMPT & DEV RULES (CANONICAL) - V12.txt
Version      : V24
Updated      : 2026-04-25 16:35 (Europe/Rome)
Status       : ACTIVE (CANONICAL / NON NEGOZIABILE)
Changelog    :
- V24: introdotte regole canoniche su `logic_occurrences`, provenance/selection delle occorrenze e obbligo di usare `trade_seq` / `run_seq` persistiti invece di rinumerazioni locali.
- V23: introdotto l'obbligo canonico di `logic_state` per i nuovi EA che vogliono Logic Indicator state-based; vietata l'inferenza implicita di boolean bar-per-bar a partire da soli eventi sparsi.
- V22: chiarito esplicitamente che validator e tooling non devono rifiutare `mre` piu' fini del `pattern_tf`; `MRE` e' il minimo EXEC ammesso, non un vincolo a restare sul tf logico del Pattern.
- V21: formalizzato che, se un evento logico mantiene `cert_dt` sul tf logico ma richiede anche un anchor operativo runtime distinto, il draft deve esporre tale anchor in `event.meta` in modo esplicito e coerente.
- V20: formalizzato che la scheda pre-registrazione deve includere obbligatoriamente una tabella riassuntiva canonica in Markdown, piu' una versione testo monospaziata human-readable quando la leggibilita' della tabella Markdown non e' sufficiente.
- V19: formalizzato che ogni Condition/Pattern/Entry/Exit deve dichiarare onset_dt, cert_dt e preset di stato visuale per il logic-indicator; la scheda canonica e' obbligatoria prima della registrazione ufficiale.
- V18: introdotta la regola R-35 che promuove il "Linear Pointer Engine" come implementazione operativa preferita per il mapping logico->EXEC, subordinata alla certificazione di equivalenza col Full Scan.
- V17: reso esplicito che la AI non deve mai generare mapping logical->EXEC per exact-match dell'anchor; il CORE puo' rifiutare script che usano o descrivono questa semantica.
- V16: formalizzato che se il logical close anchor cade prima del primo close disponibile del dataset EXEC caricato, il draft deve trattarlo come bootstrap/range truncation e saltarlo, non generare un hard-fail.
- V15: chiarito esplicitamente che su dataset BAR_START il `dt` grezzo della barra logica non puo' essere usato come close anchor per `cert_dt` o per il mapping verso EXEC.
- V14: formalizzato che le strategie multi-underlying devono usare pattern_context separati per simbolo/underlying; vietato modellare una conferma esterna come colonna aggiunta al dataframe del simbolo tradato.
- V13: formalizzato che PATTERN_REGISTRY deve essere staticamente ispezionabile dagli strumenti ALGO; ammessi riferimenti a costanti top-level staticamente risolvibili, vietata costruzione dinamica del metadata canonico.
- V12: formalizzata la regola che il mapping logico -> EXEC non puo' basarsi sulla sola coincidenza di data calendario; introdotta la gestione canonica di daily/session anchors e dataset etichettati su close di sessione.
- V11: resa obbligatoria una AI_DESCRIPTION strutturata e dettagliata, con tabelle Markdown per Variables/Constants e sezione ChartTrade Semantics motivata.
- V10: formalizzato che MRE non implica EXEC obbligatoriamente uguale al tf logico; EXEC puo' essere uguale o piu' fine.
- V10: formalizzato che i draft tecnici devono accettare i parametri pubblici nel formato runtime corrente e produrre strategy_params canonico nested.
- V10: formalizzato che pattern_symbol nel registry di draft va risolto runtime-aware e che le strategie con potenziale posizione residua devono prevedere force-exit a fine dati.
- V10: chiarito che per condizioni certificate al close della barra, cert_dt deve rappresentare il close logico della barra e non il suo start.
- V09: chiarito che il nuovo strategy_code ufficiale e' assegnato da ALGO in modo sequenziale e non puo' essere deciso dall'AI; strategy_version si usa solo su strategy_code gia' assegnato.
- V08: formalizzato che nome ufficiale, description, ai_description, strategy_code/version e registrazione DB finale di un nuovo EA richiedono conferma esplicita dell'utente.
- V08: distinto draft tecnico validato da promozione ufficiale/registrazione definitiva dell'EA.
- V07: formalizzato che i metadata canonici usati da UI/API/runtime devono essere machine-readable e fail-closed se irrisolti.
- V06: chiarite start/cert, persistence, no-lookahead e plotting sul fenomeno reale.
- V06: esplicitata la regola resolved data wins e il divieto di falsa precisione in visualizzazione.
============================================================

B4 - EA - AI PROMPT & DEV RULES (CANONICAL)
Versione: V24
Status  : ACTIVE (CANONICAL)

============================================================
1) SCOPO
============================================================
Questo documento definisce le regole operative per chi scrive, corregge o genera Expert Advisors per ALGO.
Vale sia per sviluppo umano sia per AI.

============================================================
2) REGOLE HARD-LAW
============================================================
R-01 Usa B3 come contratto canonico dell'output.
R-02 Usa il DB como source of truth per timeframe, dataset, source family e contract specs.
R-03 Vietato introdurre fallback.
R-04 Vietato introdurre alias, normalizzazioni o mapping impliciti.
R-05 Nessuna deduzione arbitraria.
R-06 AI_DESCRIPTION obbligatorio.
R-07 PATTERN_REGISTRY obbligatorio.
R-08 EA = trades + events, NON metrics.
R-09 MAE/MFE canonici per 1 contratto.
R-10 Nessuna posizione aperta nell'output finale.
R-11 Datetime e timezone non negoziabili.
R-12 Nessuna compatibilita' implicita o non dichiarata.
R-13 Nessun TF globale unico dell'EA.
R-14 Ogni Condition dichiara esplicitamente il proprio tf.
R-15 La scelta dati delle Conditions avviene a livello di Pattern Source Family, non di Condition singola.
R-16 EXEC_TF e' una scelta del run; l'EA puo' dichiarare MRE ma non puo' imporre un EXEC_TF unico assoluto.
R-17 In fase di sviluppo AI di un EA, un draft tecnico puo' essere implementato e validato prima della promozione ufficiale, ma Name, Description e AI Description definitivi richiedono conferma esplicita dell'utente.
R-18 Il salvataggio o aggiornamento ufficiale dell'EA in ALGOS/DB puo' avvenire solo dopo verifica esplicita, assegnazione coerente dell'identita' ufficiale da parte di ALGO e conferma esplicita dell'utente.
R-19 Se anche una sola Condition non dichiara un tf canonico DB, l'EA non deve essere salvato in DB: errore esplicito immediato.
R-20 start_dt/start_price e cert_dt/cert_price devono avere semantica esplicita e distinta.
R-21 Vietato usare lookahead per anticipare entry, exit, certificazioni o sopravvivenza futura di un setup.
R-22 Per un nuovo EA, `strategy_code` ufficiale e' assegnato da ALGO in modo sequenziale: AI e sviluppatore non devono inventarlo o anticiparlo. `strategy_version` si usa solo quando esiste gia' uno `strategy_code` ufficiale assegnato da ALGO.
R-23 I metadata canonici che governano UI/API/runtime devono essere disponibili in forma macchina affidabile e deterministica.
R-24 Se pattern attivi, pattern_tf, MRE o requisiti di pattern_context non sono risolvibili in modo affidabile, l'EA non e' UI-runnable e il sistema deve fallire in modo esplicito.
R-25 MRE indica il minimo EXEC ammesso, non l'unico EXEC ammesso: un EA con MRE=D non deve forzare `timeframe == "D"` se puo' operare correttamente anche con EXEC piu' fini supportati dal runtime.
R-25-bis Validator, runtime e tooling non devono interpretare `mre` come vincolo a restare sul `pattern_tf`: un Pattern `D` con `mre = M1` e' semanticamente lecito se la logica operativa richiede almeno `M1`.
R-26 Un draft tecnico deve essere compatibile con il formato runtime pubblico corrente dei params: puo' accettare input flat e/o nested, ma deve sempre emettere `strategy_params` nel formato canonico nested `variables/constants`.
R-27 Nel PATTERN_REGISTRY di un draft tecnico, `pattern_symbol` non deve essere un alias di mercato statico tipo `SPY/ES/MES`: deve essere risolto runtime-aware a partire dal simbolo reale del run.
R-28 Se la logica dell'EA puo' lasciare una posizione aperta a fine dati, il draft deve includere una force-exit esplicita a fine serie.
R-29 Per una condizione certificata al close della barra logica, `cert_dt` deve rappresentare il close logico di quella barra; usare lo start della barra come `cert_dt` e' semanticamente scorretto.
R-30 L'`AI_DESCRIPTION` deve essere strutturata, dettagliata e contenere obbligatoriamente una tabella Markdown per `Variables`, una tabella Markdown per `Constants`, una sezione `Detailed Condition Semantics` con una scheda auditabile per ogni `condition_id` canonico e una sezione `ChartTrade Semantics` con spiegazioni e motivazioni auditabili.
R-31 Il mapping tra barra logica del Pattern e barra `EXEC` non puo' basarsi sulla sola coincidenza di data calendario; deve usare l'anchor temporale canonico della barra logica.
R-32 Per dataset daily/session-based e' lecito che il timestamp canonico della barra logica cada su un giorno non-trading di calendario; l'EA non deve trattarlo come errore solo perche' non esiste una barra `EXEC` con la stessa `date`.
R-32-bis Se ALGO adotta per dataset futures higher-TF (`D/W/M`) la semantica `prices.dt = true bar start`, AI e sviluppatore non devono reintrodurre label midnight fittizie, conversioni browser-local o anchor operativi derivati da timestamp non piu' canonici.
R-33 Il `PATTERN_REGISTRY` deve essere staticamente ispezionabile dagli strumenti ALGO. Sono ammessi letterali puri e riferimenti a costanti top-level staticamente risolvibili; la costruzione dinamica del registry e' vietata.
R-34 Se una strategia usa un sottostante esterno o un simbolo diverso da quello tradato, la logica esterna deve vivere in un proprio Pattern / pattern_context con proprio `pattern_symbol`; e' vietato infilare quei dati come colonna extra del dataframe del simbolo tradato.
R-35 Per prestazioni ottimali su timeframe intraday e dataset estesi, l'implementazione operativa preferita del mapping logico->EXEC e' il "Linear Pointer Engine" (O(N+M)). L'uso di scansioni complete (Full Scan O(N*M)) e' ammesso solo per audit, debugging o laddove la densita' dei dati non rappresenti un collo di bottiglia. Ogni implementazione pointer-based deve essere certificata per equivalenza semantica col Full Scan.
R-36 Prima della registrazione ufficiale di un nuovo EA, ogni Condition / Pattern / Entry / Exit deve avere una scheda canonica che dichiari esplicitamente: significato operativo, onset_dt, cert_dt, tf di onset, tf di cert e preset di stato visuale nel logic-indicator.
R-37 Nel lessico canonico, `start_dt` del payload runtime rappresenta l'`onset_dt`: cioe' il momento in cui l'entita' nasce operativamente sul mercato. `cert_dt` rappresenta invece il momento di certificazione sul tf logico/pattern. I due campi non sono intercambiabili.
R-38 Il preset di stato visuale del logic-indicator e' parte del contratto dell'EA e deve essere deciso prima del salvataggio in DB. I preset canonici ammessi sono: `event_only`, `until_cert`, `until_entry`, `until_exit`, `while_setup_active`, `while_position_open`, `sticky_historical`, `boolean_bar_by_bar`, `custom_rule`.
R-39 La scheda pre-registrazione deve contenere obbligatoriamente una tabella riassuntiva canonica che, per ogni Condition / Pattern / Entry / Exit / Position State rilevante, distingua chiaramente almeno: categoria, significato operativo, tf logico reale, tf con cui l'entita' appare nel payload runtime corrente, motivazione di eventuali differenze e preset di stato visuale.
R-40 La tabella riassuntiva canonica deve esistere almeno in formato Markdown dentro la scheda principale. Se la densita' di colonne o testo rende il Markdown poco leggibile, deve esistere anche una seconda copia human-readable in testo monospaziato (`.txt`) coerente con la versione Markdown; le due versioni devono descrivere la stessa semantica e non possono divergere.
R-41 Se un evento logico (`CONDITION` / `PATTERN`) conserva `start_dt/cert_dt` sul proprio tf logico ma necessita anche di un anchor operativo runtime distinto per cronologia, plotting o fill-mapping, il draft deve esporre quell'anchor in `event.meta` usando nomi espliciti e auditabili come `runtime_anchor_dt`, `runtime_anchor_price`, ed eventualmente `logical_bar_start_dt` quando il dataset logico e' `BAR_START`.
R-42 Se un EA nuovo o aggiornato dichiara supporto al Logic Indicator in modalita' state-based, il payload deve esporre esplicitamente il blocco `logic_state` canonico; non e' ammesso demandare al consumer la ricostruzione implicita dello stato booleano bar-per-bar.
R-43 Il blocco `logic_state` deve esportare serie booleane dense e auditabili sul tf sorgente reale per ogni Condition / Pattern / Position State che il Logic Indicator deve rappresentare in modalita' state-based.
R-44 In assenza di `logic_state`, un consumer che richiede la visualizzazione state-based non deve inferire o normalizzare silenziosamente il booleano a partire da soli eventi sparsi; deve fallire in modo esplicito oppure limitarsi alla sola modalita' event-based dichiarata.
R-45 Se la leggibilita' auditiva di una strategia dipende dal distinguere occorrenze diverse della stessa entita' astratta, il draft deve esporre esplicitamente `logic_occurrences`; non basta affidarsi a soli `events` o a `logic_state`.
R-46 `logic_occurrences` deve essere progettato in modo generalizzabile e non strategy-specific hardcoded: la AI deve modellare occurrence, ruolo semantico, stato lifecycle, dipendenze e collegamento ai trade, senza assumere che concetti come `SL1/SL2` siano universali.
R-47 Se una occorrenza visibile sul chart non e' necessariamente quella usata dal trade, il draft deve dichiarare in modo esplicito la provenance e la selezione tramite campi occurrence-based auditabili come `depends_on_occurrence_ids`, `used_by_trade_ids` e metadata equivalenti approvati.
R-48 Se il run/trade e' persistito in DB con identificatori umani sequenziali (`run_seq`, `trade_seq`), UI/API/ChartTrade devono leggerli dal dato persistito e non rinumerare localmente run o trade.

============================================================
3) MODELLO CONCETTUALE DA USARE
============================================================
... (resto del file invariato)