Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b033896ebb | ||
|
|
1cbd5a801a | ||
|
|
dcb274e603 | ||
|
|
54504ab9fe | ||
|
|
2d59c4e94d | ||
|
|
7e3ace4ae7 | ||
|
|
28db7706b0 | ||
|
|
c618f9fc01 | ||
|
|
b80638d949 | ||
|
|
07a00cd91c | ||
|
|
fef00c5cd7 | ||
|
|
50eb330fbc | ||
|
|
58d5ea73a8 | ||
|
|
9875ab64eb | ||
|
|
9cb58822b0 | ||
|
|
02acd6059b |
No files matched your search
@@ -5,12 +5,12 @@ description: Riconcilia ledger, registro degli ordini, heartbeat e posizioni del
|
||||
|
||||
# Diagnosi di una sessione di Encelado
|
||||
|
||||
Cartella dati: `Documenti\Encelado\data` su Windows, `/data/data` nel container. Se l'utente indica un'altra cartella, usa quella.
|
||||
Cartella dati: `/data/data` nel container (`/mnt/user/appdata/encelado/data/data` su Unraid), `deploy/local/data/data` nella sandbox di sviluppo, `Documenti\Encelado\data` per l'installazione 4.0. Se l'utente indica un'altra cartella, usa quella. Leggi i file in sola lettura: con il bot acceso non scrivere niente nella cartella.
|
||||
|
||||
1. **Ledger delle decisioni** `data/ledger/decisions.jsonl` (e i mensili `decisions_YYYYMM.jsonl`): conta gli `evento` (`segnale_ingresso`, `rifiuto`, `ingresso`, `pending`, `pending_risolto`, `leg_risk_unwind`, `uscita`, `orfana_adottata`, `orfana_chiusa`, `movimento_di_cassa`, `kill_switch_*`, `recupero_*`, `comando`, `correzione`). Per ogni `rifiuto` riporta `basket`, `ts`, `unitsA`, `unitsB`, `sizing_bound`, `motivazione`.
|
||||
2. **Registro degli ordini** `data/ledger/orders.jsonl` e `data/state/pending_orders.json`: per ogni `client_ref` prendi l'ultima riga; elenca gli ordini con `esito = Pending` o `stato = Unknown` (sono le anomalie), quelli con `unita_eseguite ≠ unita_richieste` (il server ha ridotto l'ordine), gli slippage oltre 1 pip.
|
||||
3. **Basket** `data/ledger/baskets.csv`: numero, win rate, P&L netto, `exit_reason` (attenzione a `orphan_closed`, `bonifica_orfana`, `leg_risk_unwind`, `margin_guard`, `kill_switch`).
|
||||
4. **Heartbeat** `data/state/heartbeat.json` e **stato** `data/state/baskets_state.json`: ultimo battito, run, basket aperti e in attesa, `haltResidue`, `cumulativeCashFlow`, `peakNetEquity`.
|
||||
5. **Conto eToro** (solo se le chiavi sono disponibili nell'ambiente `ETORO_API_KEY`/`ETORO_USER_KEY` o via collegamento MCP, e solo in lettura): posizioni aperte (`GET api/v1/trading/info/demo/pnl`), storico (`GET api/v1/trading/info/trade/demo/history?minDate=…`). Classifica ogni posizione come `basket` (id nello stato), `orfana-bot` (id nel registro, o strumento + verso + orario entro 90 s da una riga del ledger), `esterna`.
|
||||
1. **Ledger delle decisioni** `data/ledger/decisions.jsonl` (e i mensili `decisions_YYYYMM.jsonl`, anche `_02`): conta gli `evento` (`segnale_ingresso`, `rifiuto`, `ingresso`, `pending`, `pending_risolto`, `leg_risk_unwind`, `uscita`, `orfana_adottata`, `orfana_chiusa`, `movimento_di_cassa`, `kill_switch_*` compreso `kill_switch_interrotto`, `recupero_*`, `comando`, `configurazione`, `realizzato`, `verifica_realizzato`, `correzione`). Per ogni `rifiuto` riporta `basket`, `ts`, `unitsA`, `unitsB`, `sizing_bound`, `motivazione`. Le righe `correzione` con `tipo = pnl_realizzato` danno il P&L vero delle righe della 4.0.0-5.0.0 (che erano i proceeds delle chiusure): applicale sempre prima di sommare P&L.
|
||||
2. **Registro degli ordini** `data/ledger/orders.jsonl` e `data/state/pending_orders.json` (un file per i due conti: ogni ordine ha il suo `mode`): per ogni `client_ref` prendi l'ultima riga; elenca gli ordini con `esito = Pending` o `stato = Unknown` (sono le anomalie), quelli con `unita_eseguite ≠ unita_richieste` (il server ha ridotto l'ordine), gli slippage oltre 1 pip.
|
||||
3. **Basket** `data/ledger/baskets.csv`, letto con le correzioni: numero, win rate, P&L netto (dalla 5.1 è `netProfit − fees` dello storico eToro; le righe «P&L: stima» e quelle non verificabili vanno contate a parte), `exit_reason` (attenzione a `orphan_closed`, `bonifica_orfana`, `leg_risk_unwind`, `margin_guard`, `kill_switch`), preset d'ingresso. Una posizione (marcatore `posizioni:` della motivazione) deve comparire una volta sola.
|
||||
4. **Heartbeat** `data/state/heartbeat.json` (uno per i due conti) e **stato del conto** `data/state/baskets_state.demo.json` o `baskets_state.live.json` (quello del conto in uso; il vecchio `baskets_state.json` resta solo come `.migrato`): ultimo battito, run, basket aperti e in attesa, `pendingSettlements` (chiusure che aspettano lo storico), `haltResidue`, `cumulativeCashFlow`, `peakNetEquity`, `dailyLossDay`, `pausedByOperator`.
|
||||
5. **Conto eToro** (solo via collegamento MCP dell'utente, e solo in lettura; le chiavi del bot sono cifrate in `secrets.enc` e non si leggono): posizioni aperte (`GET api/v1/trading/info/demo/pnl`), storico (`GET api/v1/trading/info/trade/demo/history?minDate=…`, P&L di record = `netProfit − fees` per `positionId`). Classifica ogni posizione come `basket` (id nello stato), `orfana-bot` (id nel registro, o strumento + verso + orario entro 90 s da una riga del ledger), `esterna`. Mai rotte che cambiano stato (ordini, chiusure).
|
||||
6. Scrivi `reports/diagnosi_<data>.csv` con separatore `;`, intestazione e colonna finale `motivazione`: una riga per anomalia (`tipo;riferimento;quando;dettaglio;motivazione`) e in fondo le righe di riepilogo. Nessuna riga del ledger va modificata: le correzioni sono righe nuove.
|
||||
7. Riassumi all'utente: cosa non torna, cosa è già stato gestito dal bot, cosa richiede una mano (chiusure su eToro, reset).
|
||||
7. Riassumi all'utente: cosa non torna, cosa è già stato gestito dal bot, cosa richiede una mano (chiusure su eToro, reset, segreti bloccati, chiusure in attesa sull'altro conto).
|
||||
@@ -6,8 +6,8 @@ description: Chiude una sessione di lavoro su Encelado: aggiorna STATE, CHANGELO
|
||||
# Chiusura della sessione: documenti e commit
|
||||
|
||||
1. `docs/STATE.md`: data, fase in corso, cosa è stato fatto in questa sessione (con i numeri: test, file, commit), prossimi passi numerati, problemi aperti, domande in attesa. È la memoria fra una sessione e l'altra: chi legge solo questo deve poter ripartire.
|
||||
2. `CHANGELOG.md`: una voce in alto con la data e il titolo della sessione; punti brevi su cosa cambia e perché, non l'elenco dei file.
|
||||
3. ADR: una scelta non ovvia = un file `docs/adr/ADR-NNNN-<slug>.md` con Contesto, Decisione, Alternative scartate, Conseguenze. Aggiorna la tabella in `CLAUDE.md` se compare un documento nuovo.
|
||||
4. `docs/QUESTIONS.md`: ogni dubbio è una riga numerata (D-xx) con il default applicato; le risposte arrivate si segnano con la data.
|
||||
5. Se sono cambiati schema del ledger, rotte dell'API, regole di rischio o file in `Documenti\Encelado`: `docs/LEDGER_SCHEMA.md`, `docs/DATA_SOURCES.md`, `docs/RISK_RULES.md`, `docs/RUNBOOK.md`, `docs/KNOWN_ISSUES.md` (togli ciò che si chiude, aggiungi ciò che resta).
|
||||
2. `CHANGELOG.md`: una voce in alto con la data e il titolo della sessione; punti brevi su cosa cambia e perché, non l'elenco dei file. Per un rilascio, la voce porta la versione e una parte «Da sapere» con ciò che l'operatore deve fare all'aggiornamento.
|
||||
3. ADR: una scelta non ovvia = un file `docs/adr/ADR-NNNN-<slug>.md` con Contesto, Decisione, Alternative scartate, Conseguenze; un ADR superato in parte riceve lo stato aggiornato e un paragrafo «Aggiornamento». Aggiorna la mappa in `CLAUDE.md` se compare un documento nuovo.
|
||||
4. `docs/QUESTIONS.md`: ogni dubbio è una riga numerata (D-xx) con il default applicato e «in attesa di conferma del proprietario»; le risposte arrivate si segnano con la data.
|
||||
5. Se sono cambiati campi o rotte dell'API web: `docs/API.md` nello stesso commit. Se sono cambiati schema del ledger, file di stato, regole di rischio, impostazioni o file in `/config` e `/data`: `docs/LEDGER_SCHEMA.md`, `docs/DATA_SOURCES.md`, `docs/RISK_RULES.md`, `docs/RUNBOOK.md`, `docs/DOCKER.md`, `docs/KNOWN_ISSUES.md` (togli ciò che si chiude, aggiungi ciò che resta).
|
||||
6. Verifica (`/encelado-verify`), poi proponi il messaggio di commit: titolo di una riga che dice cosa cambia, corpo che dice perché; un commit per sessione, un commit per fase se la sessione ne copre più d'una. Il push lo decide l'utente.
|
||||
@@ -5,12 +5,12 @@ description: Rilascio di Encelado: verifica, zip portabile, immagine Docker, tag
|
||||
|
||||
# Rilascio di Encelado
|
||||
|
||||
Presupposti: albero pulito, ultima sessione committata e pushata, `/encelado-verify` verde, Docker in esecuzione, `build/gitea.json` presente (mai committato: vedi `build/gitea.example.json`; il token deve avere anche `package: read and write`), versione decisa dall'utente (semver; la 5.0.0 è la prima con web UI e Docker).
|
||||
Presupposti: albero pulito, ultima sessione committata e pushata, `/encelado-verify` verde, Docker in esecuzione con spazio su disco (l'immagine e la sua cache pesano qualche GB), `build/gitea.json` presente (mai committato: vedi `build/gitea.example.json`; il token deve avere anche `package: read and write`), versione decisa dall'utente (semver; la 5.0.0 è la prima con web UI e Docker, la 5.1.0 la prima con la sola password nel container). `Directory.Build.props` porta la stessa versione come seme di sviluppo; quella rilasciata viene dal tag.
|
||||
|
||||
1. `dotnet msbuild build/Release.proj -t:Verifica`.
|
||||
2. `dotnet msbuild build/Release.proj -t:Rilascia -p:Versione=<x.y.z>` (note in `ENCELADO_NOTE`): pubblica la cartella portabile, costruisce l'immagine `192.168.30.23:3000/alby96/encelado:<x.y.z>` e `:latest` (i test girano anche dentro la build), crea il tag, lo spinge e lo verifica sul remoto, fa il push dell'immagine sul registro di Gitea, crea la release con lo zip portabile e il template Unraid allegati. La versione viene dal tag, non da un file.
|
||||
3. Template Unraid: aggiorna `deploy/unraid/encelado.xml` se sono cambiate variabili, porte o volumi; l'`Icon` è `assets/encelado.png` raw su Gitea (D-29). Il file finisce comunque allegato alla release con la versione nel nome.
|
||||
4. Su Unraid: *Docker ▸ Controlla aggiornamenti*; il container riparte con SIGTERM pulito e recupero dopo inattività.
|
||||
3. Template Unraid: aggiorna `deploy/unraid/encelado.xml` solo se cambiano porte, volumi o la variabile (dalla 5.1 c'è solo `ENCELADO_PASSWORD`: ogni altra impostazione sta nell'interfaccia); l'`Icon` è `assets/encelado.png` raw su Gitea (D-29). Il file finisce comunque allegato alla release con la versione nel nome.
|
||||
4. Su Unraid: *Docker ▸ Controlla aggiornamenti*; il container riparte con SIGTERM pulito e recupero dopo inattività (in Live resta fermo fino ad AVVIA con la frase). Da un container 5.0: la guida passo per passo è in `deploy/unraid/README.md` (variabili tenute per il primo avvio e poi tolte, `ENCELADO_WEB_TOKEN` rinominata `ENCELADO_PASSWORD` con lo stesso valore).
|
||||
5. `CHANGELOG.md` e `docs/STATE.md` riportano la versione rilasciata; il tag e la release hanno lo stesso testo del CHANGELOG.
|
||||
|
||||
Senza Docker: `-p:SaltaDocker=true` produce solo lo zip (non è un rilascio completo, e va detto). Non modificare `build/Release.proj` se non richiesto: la catena è condivisa con Mimante e AutoBidder.
|
||||
@@ -5,10 +5,10 @@ description: Avvia una sessione di lavoro su Encelado: legge lo stato, compila,
|
||||
|
||||
# Avvio di una sessione su Encelado
|
||||
|
||||
1. Leggi, in quest'ordine: `CLAUDE.md`, `docs/STATE.md`, `docs/PIANO_5.0.md` (se la 5.0 non è conclusa), `docs/QUESTIONS.md` (le domande in attesa), `docs/KNOWN_ISSUES.md`.
|
||||
2. Controlla l'albero di lavoro: `git status --short` e `git log --oneline -5`. Un albero sporco va capito prima di toccare qualcosa.
|
||||
1. Leggi, in quest'ordine: `CLAUDE.md`, `docs/STATE.md`, `docs/QUESTIONS.md` (le domande in attesa: dalla 5.1, D-38…D-58), `docs/KNOWN_ISSUES.md`; per toccare l'interfaccia o l'API anche `docs/API.md` e `docs/UI_GUIDELINES.md`.
|
||||
2. Controlla l'albero di lavoro: `git status --short` e `git log --oneline -5`. Un albero sporco va capito prima di toccare qualcosa (`Modifiche.txt` nella radice è un appunto dell'utente: non si committa).
|
||||
3. Compila: `dotnet build Encelado.slnx`. Se non compila, la prima cosa da fare è farlo compilare, e va detto subito.
|
||||
4. Riassumi in dieci righe: fase in corso, cosa è stato fatto nell'ultima sessione, prossimi passi, domande senza risposta, problemi aperti, esito della compilazione.
|
||||
5. Chiedi all'utente cosa fare in questa sessione. Non iniziare una fase del piano senza che sia chiaro quale.
|
||||
5. Chiedi all'utente cosa fare in questa sessione. Non iniziare un lavoro senza che sia chiaro quale.
|
||||
|
||||
Regole che valgono sempre: niente pacchetti NuGet nell'applicazione, UTC ovunque, ledger append-only, mai un ordine reale senza flag e frase `CONFERMO LIVE`, un commit a fine sessione dopo la verifica.
|
||||
Regole che valgono sempre: niente pacchetti NuGet nell'applicazione, UTC ovunque, ledger append-only, il realizzato solo dallo storico eToro, mai un ordine reale senza `run.allowLive` e la frase `CONFERMO LIVE` scritta nell'interfaccia, impostazioni solo dall'interfaccia (una sola variabile nel container), un commit a fine sessione dopo la verifica.
|
||||
@@ -1,21 +1,23 @@
|
||||
---
|
||||
name: encelado-ui
|
||||
description: Regole per toccare l'interfaccia web di Encelado: i token Material 3 e le linee guida di docs/UI_GUIDELINES.md, nessuna libreria, stesse informazioni della dashboard, test dell'HTML e dello stream.
|
||||
description: Regole per toccare l'interfaccia web di Encelado: i token e le linee guida in stile Mimante di docs/UI_GUIDELINES.md, nessuna libreria, il contratto di docs/API.md, test dei moduli e dello stream.
|
||||
---
|
||||
|
||||
# Lavorare sull'interfaccia di Encelado
|
||||
|
||||
L'interfaccia è servita dal bot (`src/Encelado.Server/Web/wwwroot/`: `index.html`, `login.html`, `app.css`, `app.js`, `icon.svg`, `manifest.webmanifest`, incorporati come `EmbeddedResource`). Le API stanno in `Web/WebHost.cs`, lo snapshot JSON in `Engine/SnapshotJson.cs`, i dati finti in `Engine/SampleSnapshot.cs`. Leggi `docs/UI_GUIDELINES.md` prima di scrivere una riga. In sintesi:
|
||||
L'interfaccia è servita dal bot (`src/Encelado.Server/Web/wwwroot/`, incorporata come `EmbeddedResource` e servita file per file con `ETag`): `index.html` (lo scheletro), `login.html` (senza script), `css/tokens.css`, `css/app.css`, `css/pages/<pagina>.css`, `js/boot.js` (il tema prima del primo disegno), `js/app.js` (ingresso, modulo ES) con i moduli `state`, `stream`, `util`, `grid`, `ui`, `charts`, `dialog`, `actions`, `baskets`, `labels`, `icons`, `flags`, `clocks`, `split` e una pagina per file in `js/pages/`. Il contratto dei dati è `docs/API.md`; il server scrive il tick in `Web/TickWriter.cs`, le sezioni in `Web/SectionJson.cs` e `Web/SystemJson.cs`, le impostazioni in `Web/SettingsApi.cs`; i dati d'esempio di `--sample` stanno in `Engine/SampleData.cs` e `SampleData.Learning.cs`. Leggi `docs/UI_GUIDELINES.md` prima di scrivere una riga. In sintesi:
|
||||
|
||||
- HTML (scritto come XHTML: tag chiusi, attributi con valore) + CSS + JavaScript vanilla; nessun framework, nessun font remoto, nessun `<script src=http…>`, nessun `@import`.
|
||||
- La UI non decide niente: legge lo snapshot (`/api/stream`, SSE, uno al secondo; `?once=1` per una sola lettura) e manda comandi (`POST /api/commands/<nome>`). Un campo nuovo nello snapshot passa da `BotSnapshot` → `SnapshotJson` → `SampleSnapshot` → `app.js` → test.
|
||||
- Ruoli di colore Material 3 (`--primary`, `--surface-container-*`, `--outline`, `--error`; `--up`/`--down` solo per P&L e stati), tema scuro di default e chiaro selezionabile (`ui.theme`), contrasto ≥ 4,5:1, cifre tabulari.
|
||||
- Componenti propri: navigation rail (80/256 px, drawer sotto 600 px), top app bar, cards, data table compatta (cards sotto 600 px), chips, buttons, dialoghi nativi `<dialog>` per conferme (kill-switch con «chiudi anche le esterne», reset con motivazione, `CONFERMO LIVE`), snackbar, linear progress, tooltip con formula e fonte su ogni numero.
|
||||
- HTML (scritto come XHTML: tag chiusi, attributi con valore) + CSS + moduli ES vanilla importati staticamente; nessun framework, nessuna libreria, nessun font remoto, nessun `<script src=http…>`, nessun `@import`, nessun `import()`.
|
||||
- La UI non decide niente: legge il tick v2 (`/api/stream`, SSE, uno al secondo condiviso; `?once=1` per una sola lettura) e le sezioni a richiesta con `watch()` quando cambia la loro versione nel tick; manda comandi (`POST /api/commands/<nome>`) e impostazioni (`POST /api/settings`) con `api()` di `util.js`, sempre con `Content-Type: application/json` (il server rifiuta gli altri con 415). Un campo nuovo passa da `EngineView` → `TickWriter`/`SectionJson` → `SampleData` → `docs/API.md` → la pagina → test.
|
||||
- Token di `css/tokens.css` (colore con un significato: neutro, accento, verde/ambra/rosso, oro), tema scuro di default e chiaro con gli stessi nomi (`ui.theme`), testo a 13 px con cifre tabulari, controlli da 30 px, niente `max-width`.
|
||||
- DOM costruito una volta e aggiornato cella per cella (`Grid` con righe a chiave); mai `innerHTML` con dati; formattatori `Intl` in cache; niente toast: finestra centrale (`dialog.js`) solo per errori, conferme e risultati importanti, con il fuoco su «Annulla» nelle azioni distruttive; tooltip su ogni numero.
|
||||
- Le parole del ledger e del motore (evento, codici, motivi d'uscita, stati degli ordini, sorgenti del log) passano da `js/labels.js`: italiano a schermo, codice nel tooltip. Un valore che può essere `null` si mostra «—», mai un conto fatto su `null`.
|
||||
- Ogni importo convertito nella valuta di visualizzazione porta nel tooltip il valore in USD e il tasso usato; il ledger resta in USD.
|
||||
- Accessibilità: tastiera completa, `aria-label`, focus visibile, `prefers-reduced-motion`, `prefers-color-scheme`.
|
||||
- Accessibilità: tastiera completa, `aria-label` sui bottoni a icona, focus visibile, `prefers-reduced-motion`, `prefers-color-scheme`.
|
||||
|
||||
Prima di dichiarare finita una modifica:
|
||||
|
||||
1. `dotnet test tests/Encelado.Tests --filter "FullyQualifiedName~EmbeddedUi|FullyQualifiedName~WebHost"` verde (HTML ben formato e senza riferimenti esterni, snapshot JSON, token, stream, storico).
|
||||
2. `dotnet run --project src/Encelado.Server -- --sample --port 8085` e controllo a occhio nel browser (dashboard, storico, log, impostazioni, larghezza da telefono).
|
||||
3. Se una pagina è cambiata, rifai gli screenshot in `docs/img/` (comando in `docs/UI_GUIDELINES.md`) e chiedi la revisione visiva all'utente.
|
||||
1. `dotnet test tests/Encelado.Tests --filter "FullyQualifiedName~EmbeddedUi|FullyQualifiedName~WebHost|FullyQualifiedName~SampleApi|FullyQualifiedName~StoppedApi"` verde (XHTML ben formato, ogni `import` risolto con i nomi esportati, nessun altro host, file serviti con il loro tipo, password, cookie, stream, forma del tick).
|
||||
2. `node --check` su una copia `.mjs` dei moduli toccati, se Node c'è (su un `.js` Node legge uno script e non vede gli errori propri dei moduli).
|
||||
3. `dotnet run --project src/Encelado.Server -- --sample --port 8085` e controllo a occhio nel browser (ogni pagina toccata, tema chiaro e scuro, larghezza da telefono, console pulita). In `--sample` comandi e salvataggi rispondono «modalità dimostrativa».
|
||||
4. Se una pagina è cambiata, rifai gli screenshot in `docs/img/` (`scripts\screenshots.ps1`, comando in `docs/UI_GUIDELINES.md`) e chiedi la revisione visiva all'utente.
|
||||
@@ -8,11 +8,12 @@ description: La verifica completa di Encelado prima di un commit: compilazione,
|
||||
Esegui nell'ordine e riporta l'esito di ciascun passo con i numeri (errori, avvisi, test superati/non superati), senza abbellire:
|
||||
|
||||
1. `dotnet build Encelado.slnx` — deve chiudere con 0 errori e 0 avvisi (`TreatWarningsAsErrors` è attivo: un avviso è un errore). Se un server locale tiene bloccata `Encelado.Server.dll`, fermalo prima (`stop` sulla sua console o Ctrl+C).
|
||||
2. `dotnet test tests/Encelado.Tests --no-build` — tutti verdi. Un test rosso si legge e si corregge; non si esclude.
|
||||
2. `dotnet test tests/Encelado.Tests --no-build` — tutti verdi. Un test rosso si legge e si corregge; non si esclude. I test di concorrenza (ciclo di vita, impostazioni, attese dopo una password errata) si possono ripetere due o tre volte per escludere instabilità.
|
||||
3. Coerenza dei file di fabbrica: `config/strategy.json` deve essere identico a `BasketStrategyConfig.DefaultJson` e `config/encelado.json` a `ConfigDefaults.Json` (ci sono test che lo verificano: se falliscono, rigenera i file dalle costanti, non il contrario).
|
||||
4. Interfaccia web: `EmbeddedUiTests` (HTML ben formato, nessun riferimento esterno, snapshot JSON) e `WebHostTests` (token, cookie, stream con uno snapshot al secondo, storico CSV) sono nella suite del passo 2; se hai toccato una pagina, anche il controllo a occhio con `--sample` (`/encelado-ui`).
|
||||
5. `dotnet msbuild build/Release.proj -t:Verifica` — la catena di rilascio compila e testa nella cartella di verifica.
|
||||
6. Se hai toccato `Dockerfile`, `deploy/` o la catena: `dotnet msbuild build/Release.proj -t:Docker` (o `docker build .`) deve produrre l'immagine; `docker run --rm <immagine> --health` non è un test valido a freddo (il server non gira): usa `docker compose up` e `docker inspect --format '{{.State.Health.Status}}' encelado`.
|
||||
7. Riepilogo: una tabella `passo;esito;dettaglio`. Se un passo fallisce, fermati lì e proponi la correzione.
|
||||
4. Interfaccia web: `EmbeddedUiTests` (XHTML ben formato, ogni `import` dei moduli risolto con i nomi esportati, nessun riferimento esterno, token con i due temi, login senza script) e `WebHostTests`, `SampleApiTests`, `StoppedApiTests` (file serviti con il loro tipo, password, cookie, attesa e 429 dopo una password errata, 415/403 per le richieste da altrove, stream con un tick al secondo, forma del tick, storico CSV) sono nella suite del passo 2; se hai toccato una pagina, anche `node --check` sui moduli e il controllo a occhio con `--sample` (`/encelado-ui`).
|
||||
5. `docs/API.md` dice la verità sui campi toccati (il contratto si aggiorna nello stesso commit).
|
||||
6. `dotnet msbuild build/Release.proj -t:Verifica` — la catena di rilascio compila e testa nella cartella di verifica.
|
||||
7. Se hai toccato `Dockerfile`, `deploy/` o la catena: `dotnet msbuild build/Release.proj -t:Docker` (o `docker build .`) deve produrre l'immagine; `docker run --rm <immagine> --health` non è un test valido a freddo (il server non gira): usa `docker compose up` e `docker inspect --format '{{.State.Health.Status}}' encelado`.
|
||||
8. Riepilogo: una tabella `passo;esito;dettaglio`. Se un passo fallisce, fermati lì e proponi la correzione.
|
||||
|
||||
Non toccare `build/` se non richiesto: è condiviso con Mimante e AutoBidder.
|
||||
@@ -2,11 +2,14 @@
|
||||
// F5 avvia il server (motore + interfaccia web) come processo locale, fuori dal
|
||||
// container, con configurazione e dati nella sandbox deploy/local (ignorata da git,
|
||||
// stesse cartelle che il compose monta come /config e /data). Il browser si apre da
|
||||
// solo appena Kestrel è in ascolto; senza token il server ascolta solo su localhost e
|
||||
// non chiede il login. "Encelado (campione)" serve l'interfaccia con dati finti, senza
|
||||
// chiavi né mercato: è quello che si usa per lavorare sulle pagine.
|
||||
// Le chiavi eToro: variabili ETORO_API_KEY/ETORO_USER_KEY nell'ambiente di VS Code,
|
||||
// oppure Impostazioni ▸ Chiavi eToro con ENCELADO_KEY_PASSPHRASE impostata qui sotto.
|
||||
// solo appena Kestrel è in ascolto. La password dell'interfaccia è "sviluppo", la
|
||||
// stessa del compose: i segreti cifrati della sandbox (chiavi eToro, token Telegram,
|
||||
// inseriti da Impostazioni) restano leggibili sia da F5 sia dal container. La password
|
||||
// serve ai segreti, non apre la rete: fuori dal container il server ascolta solo su
|
||||
// localhost (per la rete servirebbe l'argomento --listen-all).
|
||||
// "Encelado (campione)" serve l'interfaccia con dati finti, senza chiavi né mercato e
|
||||
// senza password, in cartelle temporanee: non legge né scrive Documenti\Encelado o la
|
||||
// sandbox, non tocca segreti né Telegram. È quello che si usa per lavorare sulle pagine.
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
@@ -21,6 +24,7 @@
|
||||
"stopAtEntry": false,
|
||||
"env": {
|
||||
"ENCELADO_WEB_PORT": "8080",
|
||||
"ENCELADO_PASSWORD": "sviluppo",
|
||||
"ENCELADO_CONFIG_DIR": "${workspaceFolder}/deploy/local/config",
|
||||
"ENCELADO_DATA_DIR": "${workspaceFolder}/deploy/local/data",
|
||||
"DOTNET_ENVIRONMENT": "Development"
|
||||
|
||||
@@ -2,6 +2,71 @@
|
||||
|
||||
Formato: una voce per sessione di lavoro, con data. Le voci più recenti in alto.
|
||||
|
||||
## 2026-09-30/10-01 — 5.1.0: tutto dall'interfaccia, una sola password nel container, P&L oggi corretto, nuova interfaccia in stile Mimante
|
||||
|
||||
Le richieste dell'utente (`Modifiche.txt` del 2026-09-30), poi una revisione completa del codice con le correzioni. Versione di sviluppo 5.1.0 (`Directory.Build.props`, D-50); 561 test verdi, compilazione senza avvisi. Le scelte fatte senza risposta sono in `docs/QUESTIONS.md` (D-38…D-58, in attesa di conferma); le decisioni in ADR-0010…ADR-0014.
|
||||
|
||||
### Le richieste
|
||||
|
||||
- **Solo la password nel container** (ADR-0010): l'unica variabile è `ENCELADO_PASSWORD` («Password interfaccia» nel template Unraid; `ENCELADO_WEB_TOKEN` resta come alias deprecato). Conto, chiavi eToro dei due conti, Telegram, valuta, log, avvio automatico e strategia si impostano dalla pagina. Le chiavi e il token Telegram vivono in `/config/secrets.enc`, cifrati con la password (AES-256-GCM, PBKDF2 600 000 iterazioni); se la password cambia, i segreti si sbloccano con quella precedente o si ricomincia. Il cookie di sessione è un HMAC della password e di un segreto del server (`/config/session.key`), mai la password; `POST /logout`. Al primo avvio le variabili di un container 5.0 vengono importate una volta (`import-5.1.json`) e poi ignorate ed elencate; il caricatore non legge più l'ambiente. `run.autostart` al posto di `ENCELADO_AUTOSTART`; template, compose e Dockerfile senza PUID/PGID/TZ.
|
||||
- **Paper eliminata**: il conto demo di eToro è il simulatore. Le modalità sono `Demo` e `Live` e scelgono anche il conto (`etoro.environment` non esiste più): chiuso il buco per cui `Demo` + ambiente `real` mandava ordini sul conto reale senza il cancello del Live. Il Live chiede `run.allowLive` e la frase `CONFERMO LIVE` scritta nell'interfaccia a ogni avvio, **non parte mai da solo** (allarme e avviso Telegram) e non ha più `ENCELADO_CONFIRM_LIVE` né `--confirm-live`. Il cambio Demo ↔ Live è rifiutato finché il conto non è piatto.
|
||||
- **Orologi con le bandiere** (D-49): uno per fuso delle valute trattate (Nuova Zelanda, Australia, Europa centrale/Svizzera, USA/Canada), più quello del computer solo se diverso; UTC nei tooltip.
|
||||
- **Log**: il livello è un'etichetta colorata e ogni messaggio sta su una riga (gli a capo diventano « ⏎ »); le parole del ledger sono in italiano (`labels.js`), il codice nel tooltip.
|
||||
- **Pagina Apprendimento** (`/api/learning`): dataset, criteri di attivazione, pesi imparati e contributi, bandit 3×3 con gli intervalli di credibilità, ultimo ciclo con la valutazione completa, AUC mobile, calibrazione, proposte, registro, file, intuizioni. «Esegui ciclo» in ogni stato: il ciclo gira in background con un solo scrittore dei file (ADR-0014; nella 5.0 il ciclo dalla pagina era un secondo scrittore dei modelli e il settimanale fermava il thread di decisione).
|
||||
- **Nuova interfaccia in stile Mimante** (ADR-0013): dashboard compatta che riassume tutto in una schermata (9 tessere, basket, eventi, quotazioni, registro) e nove pagine di dettaglio (Basket, Posizioni, Mercato, Storico, Apprendimento, Log, Sistema, Impostazioni); lo stato di Telegram e il dettaglio del collegamento eToro passano in Sistema. Moduli ES vanilla, nessuna libreria, tema scuro e chiaro.
|
||||
- **Layout fluido**: niente larghezza massima, niente fascia grigia a destra; tabelle che cedono colonne e scorrono nel loro pannello, mai la pagina; provata da 420 a 2560 px.
|
||||
- **Controlli allineati**: barre strumenti su una riga, tutti i controlli alti 30 px (anche «Segui» del Log, ora una levetta allineata al filtro e alla ricerca).
|
||||
- **Niente valuta nella barra in alto**: si sceglie in Impostazioni ▸ Interfaccia.
|
||||
- **Impostazioni applicate a caldo**: ogni campo dice quando vale (⚡ subito, ⚙ nel motore in esecuzione, ↻ con un riavvio automatico del motore che non chiude i basket) e la risposta lo dice campo per campo; tutta la strategia, il rischio, il recupero e l'apprendimento sono nel form (Avanzate chiuso).
|
||||
- **Preset fisso**: si sceglie in Impostazioni ▸ Strategia ed è parte della strategia; il comando per cambiarlo a caldo è tolto ovunque (web, console, Telegram). Un cambio vale per i basket nuovi: quelli aperti tengono z di stop, aggiunte, TP, perdita massima e preset con cui sono entrati.
|
||||
- **Stato fuori dal menu**: le scritte «in esecuzione» e «demo» in fondo al menu diventano la pill del motore nella barra in alto (pallino colorato per lo stato, `DEMO`/`LIVE` per il conto).
|
||||
- **«P&L oggi» corretto** (ADR-0011): il vecchio numero (circa 47 000 USD su 139 000 di equity) sommava i `proceeds` delle chiusure, cioè margine restituito **più** profitto. Sul conto demo, dal 23 al 30 settembre, il bot ha chiuso 102 posizioni con un risultato netto di **−269,42 USD**, mentre la somma registrata superava i 903 000 USD; il 24/9 sei chiusure da +48,34 USD di netto contavano come circa 53 900. Ora il realizzato di ogni posizione è quello dello **storico di eToro** (`netProfit − fees`, per `positionId`), lo stesso della pagina Storico; «P&L oggi» è il realizzato delle posizioni del bot chiuse oggi (UTC), con le stime provvisorie segnate «stima» e «—» quando non è noto; accanto c'è la variazione dell'equity netta da mezzanotte. Le righe di `baskets.csv` aspettano lo storico in una coda persistente (dopo 30 minuti la stima, che non addestra). La perdita giornaliera, che con i proceeds non scattava mai dopo la prima chiusura del giorno, guarda l'equity netta dalla mezzanotte. **Il passato è corretto con righe nuove**: all'avvio una verifica idempotente scrive righe `correzione` (`pnl_realizzato`) per le righe della 4.0.0-5.0.0, `lastNOutcomes` è neutralizzata prima della correzione, i modelli addestrati sui proceeds vengono messi da parte e la logistica riaddestrata, il bandit riparte dal prior.
|
||||
- **Interfaccia leggera** (ADR-0012): il motore pubblica viste immutabili e il server costruisce un solo tick al secondo per tutti i browser (niente se nessuno guarda), con le righe di log nuove e le versioni delle sezioni; le parti pesanti si leggono a richiesta con `ETag`; il browser aggiorna cella per cella solo la pagina visibile. Circa 64 ms di lavoro ogni 10 s sulla dashboard, tick da ~40 KB a pochi KB. Calendario e notizie si scaricano in background, anche a motore fermo.
|
||||
- `--sample` serve dati d'esempio coerenti per ogni rotta; `/api/info` diventa un alias di `/api/system`, `/api/research` è assorbita da `/api/learning`; screenshot rifatti (`docs/img/`, 11 pagine più il tema chiaro e il telefono).
|
||||
|
||||
### Correzioni della revisione
|
||||
|
||||
Una revisione del codice della 5.1 ha trovato 51 problemi; quelli confermati sono corretti, ciascuno con un test che fallisce senza la correzione.
|
||||
|
||||
- **Ciclo di vita del motore**: un solo lucchetto per avvio, arresto, riavvii automatici e ciclo di apprendimento a motore fermo; FERMA durante un avvio aspetta il motore e lo ferma (prima restava un motore che operava irraggiungibile); un riavvio automatico non annulla più un FERMA arrivato prima; AVVIA subito dopo FERMA aspetta che il motore precedente lasci la cartella dati. Un kill-switch, una chiusura o la chiusura dei residui in corso non vengono mai interrotti da FERMA o da un salvataggio (409); solo `docker stop` li interrompe dopo 30 s, registrando il residuo. Ogni comando riceve una risposta («comando interrotto: il motore si è fermato», 504 con un messaggio per un'attesa scaduta, mai 500). La chiusura all'arresto (`closeOnShutdown`) è un comando sul thread di decisione, che prima blocca le entrate. «Esegui ciclo» risponde 409 finché il ciclo di decisione non è partito. Lo stream non tiene più un iscritto il cui primo tick fallisce. L'heartbeat pubblica il suo intervallo e `/api/health` usa 3 × intervallo + 15 s.
|
||||
- **Conti**: lo stato del motore è **per conto** (`baskets_state.demo.json`, `baskets_state.live.json`, D-53): passare da un conto all'altro non sovrascrive più chiusure in attesa del P&L, equity stop, kill-switch, residuo, pausa e picco dell'altro. Il registro degli ordini resta unico ma ogni motore tocca solo i suoi. La guardia del cambio di conto è un comando sul thread di decisione (prima leggeva la vista, piatta a metà di un ingresso), con un nuovo controllo dopo l'arresto e l'annullamento del salvataggio se il conto non è piatto. All'avvio il saldo si giudica solo quando lo storico mostra ogni chiusura: una perdita non ancora nello storico non diventa più un prelievo.
|
||||
- **Soldi**: la perdita giornaliera, raggiunta, **blocca fino alle 00:00 UTC anche se l'equity recupera** (D-52), nel motore e nel backtest, anche dopo un riavvio (prima il blocco cadeva appena l'equity risaliva, mentre l'interfaccia prometteva «fino a domani»); un calo del saldo che lo storico non spiega ancora sospende senza bloccare la giornata (D-54). Una posizione finisce in `baskets.csv` una volta sola (prima una chiusura vista da due percorsi poteva raddoppiare il P&L dei riepiloghi). La verifica del realizzato ha una soglia per conto (prima le righe Live restavano con i proceeds e li insegnavano ai modelli). Le gambe singole della 4.0-5.0 si abbinano alla loro nota senza indovinare. La riga di un'aggiunta richiusa non trasforma più le gambe del basket in orfane. La cache dello Storico rispetta il periodo chiesto («anno» e «tutto» non escono più calcolati su 90 giorni). La riga di `baskets.csv` e il premio del bandit nominano il preset con cui il basket è entrato. Il kill-switch fa ciò che sceglie l'operatore nel dialogo (prima chiudeva le esterne anche con la casella spenta, se l'impostazione era accesa) (D-55).
|
||||
- **Segreti e web**: un file 5.0 con `Live` e ambiente `demo` resta sul conto demo dopo un salvataggio qualsiasi (prima diventava Live, scavalcando guardia, chiavi e frase). Una password errata costa un'attesa anche via Bearer, per indirizzo e fino a 30 s, e durante l'attesa non si controlla niente (D-56). Le richieste da altri siti sono rifiutate (`Content-Type: application/json` obbligatorio sotto `/api/`, controllo di `Origin` e `Sec-Fetch-Site`, `Host` locale senza password). `--sample` lavora in cartelle temporanee e non tocca più segreti, configurazione o il bot Telegram dell'operatore. La rete si apre solo nel container o con `--listen-all` (D-57). Il tick porta `statusLines` (le righe della striscia della dashboard, prima salvate e mai lette). L'importazione segue l'ordine delle chiavi della 5.0; un `secrets.enc` con un numero di iterazioni assurdo è danneggiato, non un avvio fermo per minuti; `run-docker` non stampa più la password; la pagina Apprendimento a motore fermo segue subito le modifiche di `strategy.json`.
|
||||
- **Apprendimento**: i contributi mostrati spiegano sempre la `p_ML` accanto (vengono dal modello che l'ha data, salvati con l'ingresso; dopo un riavvio un basket aperto riprende la sua p); il ritiro dei modelli è tutto o niente e non si ripete; dopo la verifica del realizzato la sessione rilegge esiti e conteggio dal ledger corretto; i basket etichettati sono contati come li conta il dataset ovunque; a motore fermo la pagina segue subito le correzioni e tiene l'ultima lettura buona di un file illeggibile; un braccio del bandit mai provato non è mai «il migliore».
|
||||
- **Interfaccia**: impostazioni salvabili dopo due modifiche allo stesso campo; gli stati di un basket spento non sono più nascosti; filtri ricordati sempre visibili; quotazioni del Mercato che seguono il tick; «—» invece di 0 per i valori sconosciuti; fuoco su «Annulla» nelle conferme distruttive (un Invio tenuto premuto non esegue più un kill-switch); `Content-Type: application/json` su ogni POST e DELETE.
|
||||
- **Ledger**: la rotazione mensile delle decisioni va solo in avanti e non sovrascrive mai un file già ruotato (l'ultima barra del mese valutata dopo la mezzanotte faceva ruotare all'indietro e perdeva una riga).
|
||||
|
||||
### Correzioni della seconda revisione (2026-10-01)
|
||||
|
||||
Una seconda verifica indipendente delle correzioni ha trovato nove punti rimasti aperti; ciascuno ha un test che lo riproduce.
|
||||
|
||||
- **Stato della 5.0 al conto giusto**: il `mode` di `baskets_state.json` della 5.0 era la modalità, non il conto. Un file `Live` scritto con `etoro.environment` demo finiva nel file del conto reale, e al primo Live il saldo del demo diventava un «prelievo» di oltre 100 000 USD, con equity stop e perdita giornaliera misurati sulla cifra sbagliata; un file Paper riprendeva basket simulati sul conto demo. Ora l'importazione registra su che conto operava la 5.0 (`legacyState` in `import-5.1.json`) e il file va lì; Paper, o una modalità diversa, non vengono ripresi.
|
||||
- **Comandi critici fino alla fine**: un kill-switch, una chiusura o la chiusura dei residui tengono fermi FERMA e i riavvii finché il motore li ha in mano, non finché chi li ha chiesti aspetta: chiudere la scheda, una risposta 504 dopo 120 s o Telegram spento a metà `/kill` non liberano più FERMA a metà kill-switch.
|
||||
- **Chiavi salvate mentre il conto cambia**: dopo la verifica (fino a 25 s) si rilegge il conto in uso; chiavi che non sono più del conto del motore non lo riavviano, e un motore Live non viene mai riavviato senza la frase (prima restava fermo, con i basket reali sui soli stop nativi).
|
||||
- **Guardia del cambio di conto**: il motore riconcilia con il conto prima di contare, così una gamba rimasta sola (richiusura rifiutata) conta come orfana invece di restare sul conto lasciato; posizioni non lette: cambio rifiutato.
|
||||
- **Perdita giornaliera con lo storico in ritardo**: un calo del saldo non ancora spiegato sospende le entrate fino alla spiegazione anche se l'equity recupera (prima tornavano permesse), e la lettura che lo spiega blocca la giornata se, al minimo toccato nel frattempo, la perdita di trading superava la soglia (prima non la bloccava mai); un movimento di cassa non la blocca. Il cruscotto mostra la sospensione per tutto il tempo.
|
||||
- **Apprendimento, il secondo conto**: le righe della 4.0-5.0 dell'altro conto si correggono quando quel conto gira; quell'avvio ora neutralizza di nuovo `lastNOutcomes` fino ad allora e rifà la logistica sulle etichette corrette (prima restavano l'etichetta sbagliata nel modello e una feature sbagliata, non mascherata, nelle righe della sessione intermedia).
|
||||
- **Pagina Apprendimento a motore fermo**: un file mai letto bene resta «valori iniziali» anche alle letture successive (prima diventava «l'ultima lettura buona» mostrando il prior); lo stesso per `last_cycle.json`.
|
||||
- **Accesso**: il cookie di sessione contiene un segreto del server (`/config/session.key`, D-56 aggiornata), quindi non è più un tentativo di password: una scheda rimasta aperta dopo un cambio di password non tiene più fuori la password giusta (prima 429 finché restava aperta), una pagina già entrata non viene fermata da chi tenta password dallo stesso indirizzo né gli azzera il conto, e l'interfaccia torna alla pagina di accesso a un 401 o 429. Serve un nuovo accesso dopo l'aggiornamento. La risposta a una password errata arriva solo a attesa davvero finita (un nuovo tentativo immediato riceveva ancora 429).
|
||||
- **Test**: il preset d'ingresso è verificato dall'esecutore alla posizione e nello stato salvato (togliere una delle due righe non faceva fallire nessun test).
|
||||
|
||||
### Da sapere (aggiornamento dalla 5.0)
|
||||
|
||||
1. Al primo avvio della 5.1 **tieni le variabili della 5.0** (anche `ENCELADO_KEY_PASSPHRASE` se le chiavi erano in `etoro.keys.enc`): vengono importate una volta. **Rinomina `ENCELADO_WEB_TOKEN` in `ENCELADO_PASSWORD` con lo stesso valore**, così i segreti restano leggibili. Poi togli dal container tutte le altre variabili (la striscia degli allarmi e Sistema ▸ Segreti le elencano). Passo per passo in `deploy/unraid/README.md`.
|
||||
2. Con una password diversa i segreti risultano bloccati: Impostazioni ▸ Conto ▸ «Sblocca con la password precedente», o «Ricomincia» e reinserisci chiavi e token.
|
||||
3. Il primo avvio sposta lo stato nel file del conto su cui operava la 5.0 (`baskets_state.json` resta come `.migrato`; lo stato di Paper non viene ripreso), corregge il realizzato della 4.0.0-5.0.0 con righe nuove e ritira una volta i modelli addestrati sui proceeds: poi premi **Esegui ciclo** e segna `respinta` in `knowledge/proposals.csv` le proposte nate dalle etichette sbagliate.
|
||||
4. I messaggi Telegram e i log già inviati dalla 4.0.0 alla 5.0.0 con il «netto» e il «P&L oggi» sbagliati restano come sono: il ledger è corretto, la cronologia no.
|
||||
5. In Live il motore non riparte più da solo dopo un riavvio: AVVIA e `CONFERMO LIVE`, ogni volta.
|
||||
6. Gli script che chiamano l'API devono mandare `Content-Type: application/json` su ogni POST e DELETE; dietro un reverse proxy il proxy deve passare l'`Host` originale (`docs/DOCKER.md`).
|
||||
7. Il preset si cambia solo da Impostazioni ▸ Strategia; il comando `preset` (console, web) non esiste più.
|
||||
8. Dopo l'aggiornamento serve un nuovo accesso alla pagina (il cookie contiene ora un segreto del server, `/config/session.key`; cancellarlo chiude tutte le sessioni).
|
||||
|
||||
## 2026-09-23 — 5.0.0 rilasciata; workflow Gitea Actions; guida Unraid
|
||||
|
||||
- **Versione 5.0.0**: tag `v5.0.0`, immagine `192.168.30.23:3000/alby96/encelado:5.0.0` e `:latest` sul registro dei container di Gitea, release con la cartella portabile e il template Unraid allegati (catena `-t:Rilascia`).
|
||||
- `.gitea/workflows/ci.yml` (compilazione con avvisi come errori, test, `docker build` a ogni push) e `release.yml` (immagine sul registro e release a ogni tag `v*`, idempotente rispetto alla catena). Servono un runner e il segreto `REGISTRY_TOKEN`, oggi assenti.
|
||||
- `deploy/unraid/README.md`: installazione passo per passo (registro in HTTP, template, campi, primo avvio, aggiornamento).
|
||||
|
||||
## 2026-09-23 — 5.0, Fasi 6-9: solo container, interfaccia web, Docker e Unraid, pulizia
|
||||
|
||||
- **Ritirata la finestra WPF** (D-28, ADR-0007): `src/Encelado.Bot` diventa la libreria `src/Encelado.Engine`; l'eseguibile è `src/Encelado.Server` (Kestrel, nessun NuGet) che ospita il motore e serve l'interfaccia. Chiavi eToro da variabili d'ambiente o dal file cifrato `etoro.keys.enc` (AES-256-GCM, `ENCELADO_KEY_PASSPHRASE`) al posto di DPAPI. Cartelle `/config` e `/data` nel container, `Documenti\Encelado` fuori.
|
||||
|
||||
@@ -4,25 +4,26 @@
|
||||
|
||||
## Scopo
|
||||
|
||||
Bot di trading in C# (.NET 10) su **eToro** con la strategia "Correlation Baskets": cinque basket di due coppie forex correlate, ingresso quando il cross sintetico diverge (z-score), uscita quando converge o al take-profit di basket, stop di basket obbligatorio, cost gate sullo spread reale, ledger completo, feed gratuiti di calendario e notizie, livelli di apprendimento 0-3 costruiti da zero. È l'unica strategia del repository: i motori precedenti (Binance, cTrader/proba, ricerca) sono stati rimossi il 2026-09-16 (ADR-0004) e vivono solo nella storia git. Il bot opera da solo in ogni modalità (ADR-0005): `Paper`, `Demo` (default), `Live`. Dalla 5.0 gira **solo in un container** (ADR-0007, ADR-0008): un processo `Encelado.Server` che ospita il motore e serve l'interfaccia web; la finestra WPF non esiste più.
|
||||
Bot di trading in C# (.NET 10) su **eToro** con la strategia "Correlation Baskets": cinque basket di due coppie forex correlate, ingresso quando il cross sintetico diverge (z-score), uscita quando converge o al take-profit di basket, stop di basket obbligatorio, cost gate sullo spread reale, ledger completo, feed gratuiti di calendario e notizie, livelli di apprendimento 0-3 costruiti da zero. È l'unica strategia del repository: i motori precedenti (Binance, cTrader/proba, ricerca) sono stati rimossi il 2026-09-16 (ADR-0004) e vivono solo nella storia git. Il bot opera da solo in ogni modalità (ADR-0005): `Demo` (default) e `Live`; dalla 5.1 la modalità è anche il conto e `Paper` non esiste più (ADR-0010). Dalla 5.0 gira **solo in un container** (ADR-0007, ADR-0008): un processo `Encelado.Server` che ospita il motore e serve l'interfaccia web; la finestra WPF non esiste più. Dalla 5.1 **tutto si imposta dall'interfaccia** e il container ha una sola variabile, la password (ADR-0010).
|
||||
|
||||
## Mappa dei documenti
|
||||
|
||||
| File | Contenuto |
|
||||
|---|---|
|
||||
| `docs/STATE.md` | stato corrente, fase, ultima sessione, prossimi passi, problemi aperti |
|
||||
| `docs/ARCHITECTURE.md` | progetti, flusso dati, macchine a stati, interfacce, API web |
|
||||
| `docs/ARCHITECTURE.md` | progetti, flusso dati, macchine a stati, interfacce, viste pubblicate e ciclo di vita, impostazioni e segreti, stato per conto, apprendimento |
|
||||
| `docs/API.md` | il contratto dell'API web fra server e interfaccia: tick, sezioni, comandi, impostazioni, segreti, accesso; i nomi dei campi valgono lì |
|
||||
| `docs/STRATEGY.md` | logica dei basket, cross sintetici, formule, preset, aspettative oneste, numeri |
|
||||
| `docs/ML_AND_LEARNING.md` | livelli 0-3, feature, label, addestramento, attivazione, esclusioni, comando `learn` |
|
||||
| `docs/DATA_SOURCES.md` | ogni fonte (URL, formato, limiti), schema dei file in `data/` |
|
||||
| `docs/LEDGER_SCHEMA.md` | schema di `decisions.jsonl`, `orders.jsonl`, `baskets.csv`, `trials.csv`, `calibration.csv`, `preregistrazione.csv`, `proposals.csv` |
|
||||
| `docs/ML_AND_LEARNING.md` | livelli 0-3, feature, label, ciclo in background, pagina Apprendimento, attivazione, esclusioni, comando `learn` |
|
||||
| `docs/DATA_SOURCES.md` | ogni fonte (URL, formato, limiti), storico eToro come P&L di record, schema dei file in `/config` e `/data` |
|
||||
| `docs/LEDGER_SCHEMA.md` | schema di `decisions.jsonl`, `orders.jsonl`, `baskets.csv`, correzioni, stato per conto, `pending_orders.json`, `data/models`, `trials.csv`, `calibration.csv`, `preregistrazione.csv`, `proposals.csv` |
|
||||
| `docs/RISK_RULES.md` | regole di sicurezza con i default e chi può cambiarle |
|
||||
| `docs/RUNBOOK.md` | avvio, arresto, kill-switch, reset, riconciliazione, chiavi, errori API, checklist |
|
||||
| `docs/DOCKER.md`, `deploy/unraid/README.md` | immagine, volumi, variabili, healthcheck, aggiornamento; template Unraid |
|
||||
| `docs/UI_GUIDELINES.md` | l'interfaccia web: token Material 3, componenti, pagine, screenshot |
|
||||
| `docs/QUESTIONS.md` | domande poste per fase, risposte o default applicati, con data |
|
||||
| `docs/RUNBOOK.md` | avvio, aggiornamento dalla 5.0, arresto, kill-switch, reset, cambio di conto, segreti, riconciliazione, errori API, checklist |
|
||||
| `docs/DOCKER.md`, `deploy/unraid/README.md` | immagine, volumi, la sola variabile, rete, healthcheck, aggiornamento; template Unraid e guida all'aggiornamento 5.0 → 5.1 |
|
||||
| `docs/UI_GUIDELINES.md` | l'interfaccia web in stile Mimante: token, componenti, pagine, flusso dei dati, prestazioni, screenshot |
|
||||
| `docs/QUESTIONS.md` | domande poste per fase, risposte o default applicati, con data (5.1: D-38…D-58, in attesa di conferma) |
|
||||
| `docs/PIANO_5.0.md`, `docs/PROMPT_5.0.md`, `docs/POSTMORTEM_ordini_pendenti.md` | il piano della 5.0 (fasi, stime, decisioni vincolanti), la specifica originale e il post-mortem delle gambe orfane del 16-21/9/2026 |
|
||||
| `docs/GLOSSARY.md`, `docs/KNOWN_ISSUES.md`, `CHANGELOG.md`, `docs/adr/` | glossario, problemi noti, cronologia, decisioni architetturali |
|
||||
| `docs/GLOSSARY.md`, `docs/KNOWN_ISSUES.md`, `CHANGELOG.md`, `docs/adr/` | glossario, problemi noti, cronologia, decisioni architetturali (ADR-0001…ADR-0014) |
|
||||
| `build/README.md` | catena di verifica, pacchetto (immagine Docker) e rilascio; `.gitea/workflows/` per le Actions |
|
||||
|
||||
## Progetti
|
||||
@@ -30,8 +31,8 @@ Bot di trading in C# (.NET 10) su **eToro** con la strategia "Correlation Basket
|
||||
```
|
||||
src/Encelado.Core logica pura, zero I/O, AOT/trim-compatibile
|
||||
src/Encelado.Etoro client HTTP di eToro Public API
|
||||
src/Encelado.Engine motore, ledger, feed, configurazione, impostazioni, storico, Telegram (ex Encelado.Bot senza UI)
|
||||
src/Encelado.Server l'eseguibile: Kestrel, API JSON scritta a mano, SSE, UI incorporata (Web/wwwroot)
|
||||
src/Encelado.Engine motore, ledger, feed, configurazione, segreti, impostazioni, storico, Telegram (ex Encelado.Bot senza UI)
|
||||
src/Encelado.Server l'eseguibile: Kestrel, API JSON scritta a mano, SSE, UI incorporata (Web/wwwroot: moduli ES vanilla)
|
||||
tools/Encelado.Backtest ticks, baskets, falsify, learn
|
||||
tests/Encelado.Tests xunit
|
||||
deploy/docker, deploy/unraid entrypoint del container, template Unraid
|
||||
@@ -39,16 +40,19 @@ deploy/docker, deploy/unraid entrypoint del container, template Unraid
|
||||
|
||||
## Convenzioni
|
||||
|
||||
- **C#**, `Nullable` e `TreatWarningsAsErrors` attivi. Identificatori e commenti tecnici in inglese; documentazione, report e colonna `motivazione` in italiano.
|
||||
- **C#**, `Nullable` e `TreatWarningsAsErrors` attivi. Identificatori e commenti tecnici in inglese; documentazione, report, testi dell'interfaccia e colonna `motivazione` in italiano.
|
||||
- **Nessun pacchetto NuGet.** Solo BCL e i framework reference dell'SDK (`Microsoft.AspNetCore.App` nel Server) nei progetti dell'applicazione; xunit nei test. Nessuna libreria JavaScript o CSS: l'interfaccia è HTML, CSS e JS vanilla incorporati.
|
||||
- **Tabelle**: CSV con separatore `;`, header, ultima colonna `motivazione`; JSONL append-only per ledger e notizie; JSON per modelli e stato. Scritture atomiche (`.tmp` + `File.Move`), rotazione mensile. **Nessuna riga del ledger viene mai modificata**: le correzioni sono righe nuove con `evento = correzione`.
|
||||
- **Tabelle**: CSV con separatore `;`, header, ultima colonna `motivazione`; JSONL append-only per ledger e notizie; JSON per modelli e stato. Scritture atomiche (`.tmp` con nome unico + `File.Move`, `AtomicFile`), rotazione mensile. **Nessuna riga del ledger viene mai modificata**: le correzioni sono righe nuove con `evento = correzione`.
|
||||
- **Tempo**: UTC ovunque; conversione solo in UI. `CultureInfo.InvariantCulture` per ogni parsing e formattazione su file.
|
||||
- **Concorrenza**: un solo thread di decisione; I/O asincrono; `Channel<T>` fra ingestion, strategia, esecuzione e UI.
|
||||
- **Concorrenza**: un solo thread di decisione; I/O asincrono; `Channel<T>` fra ingestion, strategia, esecuzione e UI. Il motore pubblica viste immutabili (`EngineView`) e il web legge solo quelle; tutto ciò che cambia il motore è un comando eseguito sul suo thread; avvio, arresto e riavvii passano da un solo lucchetto del supervisore (ADR-0012).
|
||||
- **Riproducibilità**: seed fisso 42 per ogni componente stocastica; ogni run scrive `run_id`, hash della configurazione e versione del codice nel ledger.
|
||||
- **Cartelle a runtime**: nel container `/config` (encelado.json, strategy.json, instruments.json, `etoro.keys.enc`, file `STOP`) e `/data` (`data/`, `knowledge/`, `reports/`, `results/`, `logs/`); fuori dal container (solo sviluppo) la sandbox `deploy/local/` (`ENCELADO_CONFIG_DIR` + `ENCELADO_DATA_DIR`, usata da F5 e dagli script) o, senza variabili, `Documenti\Encelado\`. Credenziali solo nelle variabili `ETORO_API_KEY`/`ETORO_USER_KEY` o nel file cifrato (AES-256-GCM, passphrase `ENCELADO_KEY_PASSPHRASE`); token Telegram solo in `TELEGRAM_BOT_TOKEN` (chat in `TELEGRAM_CHAT_ID`); token dell'interfaccia in `ENCELADO_WEB_TOKEN`.
|
||||
- **Esecuzione (5.0)**: ogni ordine entra nel registro `data/state/pending_orders.json` prima dell'HTTP e l'esito si legge per `orderId` (il server non registra il `referenceId`); una gamba senza esito porta il basket in `PendingA`/`PendingB`, mai in un rifiuto; ogni posizione del conto è `basket`, `orfana-bot` (adottata e chiusa) o `esterna` (mai toccata); la size è il minimo fra rischio e margine (`strategy.json` → `risk`); il kill-switch verifica la piattezza sul conto e dichiara `Halted-Residuo` se resta qualcosa; heartbeat e recupero dopo inattività (`recovery`); un solo bot per cartella dati (`instance.lock`).
|
||||
- **Interfaccia**: navigation rail a sinistra (Dashboard, Storico ordini, Log, Impostazioni), barra in alto (titolo, ora UTC e nel fuso, valuta, AVVIA/FERMA, KILL-SWITCH), pagine sotto. Nella dashboard solo le informazioni principali; i dettagli nei tooltip e nel log. La UI non decide niente: legge lo snapshot via SSE e manda comandi via `POST /api/commands/<nome>`. Gli orari a schermo sono nel fuso scelto (`ui.timeZone`, `TZ`); il log porta l'offset, il ledger è UTC. Regole complete in `docs/UI_GUIDELINES.md`.
|
||||
- **Verifica visiva**: `scripts\screenshots.ps1` (server `--sample` + Edge headless, `docs/UI_GUIDELINES.md`); i test `EmbeddedUiTests` e `WebHostTests` coprono HTML, JSON, token e stream.
|
||||
- **Cartelle a runtime**: nel container `/config` (encelado.json, strategy.json, instruments.json, `secrets.enc`, `import-5.1.json`, file `STOP`) e `/data` (`data/`, `knowledge/`, `reports/`, `results/`, `logs/`); fuori dal container (solo sviluppo) la sandbox `deploy/local/` (`ENCELADO_CONFIG_DIR` + `ENCELADO_DATA_DIR`, usata da F5 e dagli script) o, senza variabili, `Documenti\Encelado\`.
|
||||
- **Configurazione e segreti (5.1, ADR-0010)**: ogni impostazione si cambia da Impostazioni nell'interfaccia e il bot la applica subito (nel processo, nel motore sul suo thread, o con un riavvio automatico del motore che non chiude niente). L'unica variabile del container è `ENCELADO_PASSWORD` (alias deprecato `ENCELADO_WEB_TOKEN`): apre l'interfaccia e cifra i segreti. Chiavi eToro dei due conti e token Telegram solo in `/config/secrets.enc` (AES-256-GCM, chiave PBKDF2 dalla password), inseriti e verificati da Impostazioni; mai nell'ambiente, nel log o in `encelado.json`. Le variabili della 5.0 vengono importate una volta al primo avvio e poi ignorate. Il caricatore non legge l'ambiente.
|
||||
- **Modalità (5.1)**: `Demo` (conto demo) o `Live` (conto reale); `Paper` è stata eliminata. Il preset è fisso in `strategy.json` (Impostazioni ▸ Strategia) e vale per i basket nuovi.
|
||||
- **Esecuzione (5.0)**: ogni ordine entra nel registro `data/state/pending_orders.json` prima dell'HTTP e l'esito si legge per `orderId` (il server non registra il `referenceId`); una gamba senza esito porta il basket in `PendingA`/`PendingB`, mai in un rifiuto; ogni posizione del conto è `basket`, `orfana-bot` (adottata e chiusa) o `esterna` (mai toccata, salvo scelta esplicita nel kill-switch); la size è il minimo fra rischio e margine (`strategy.json` → `risk`); il kill-switch verifica la piattezza sul conto e dichiara `Halted-Residuo` se resta qualcosa; heartbeat e recupero dopo inattività (`recovery`); un solo scrittore per cartella dati (`instance.lock`).
|
||||
- **Soldi e stato (5.1)**: il realizzato di ogni posizione è quello dello storico eToro (`netProfit − fees`), mai i `proceeds` della chiusura (ADR-0011); una posizione finisce in `baskets.csv` una volta sola; la perdita giornaliera, raggiunta, blocca le entrate fino alle 00:00 UTC (D-52); lo stato del motore è **per conto** (`baskets_state.demo.json`, `baskets_state.live.json`, D-53) e il cambio Demo ↔ Live lo decide il motore, rifiutandolo finché il conto non è piatto.
|
||||
- **Interfaccia (5.1, ADR-0013)**: stile Mimante. Menu a sinistra con nove pagine (Dashboard, Basket, Posizioni, Mercato, Storico, Apprendimento, Log, Sistema, Impostazioni), barra in alto (logo, pill del motore con il conto, pill eToro, numeri, orologi delle valute con le bandiere, allarme, KILL, tema, accensione), striscia degli allarmi sotto; niente selettore della valuta in barra. Nella dashboard tutto in una schermata; i dettagli nelle pagine e nei tooltip. La UI non decide niente: legge il tick v2 via SSE e le sezioni a richiesta con `ETag`, manda comandi via `POST /api/commands/<nome>` e impostazioni via `POST /api/settings`, sempre con `Content-Type: application/json`. Le parole del ledger passano da `js/labels.js` (italiano a schermo, codice nel tooltip). Gli orari a schermo sono nel fuso del browser; il log porta l'offset, il ledger è UTC. Regole complete in `docs/UI_GUIDELINES.md`, contratto dei dati in `docs/API.md`.
|
||||
- **Verifica visiva**: `scripts\screenshots.ps1` (server `--sample` + Edge headless, `docs/UI_GUIDELINES.md`); i test `EmbeddedUiTests` e `WebHostTests` coprono HTML, moduli e `import`, file serviti, password e stream. I moduli toccati si controllano anche con `node --check` su una copia `.mjs`.
|
||||
|
||||
## Comandi
|
||||
|
||||
@@ -56,35 +60,40 @@ deploy/docker, deploy/unraid entrypoint del container, template Unraid
|
||||
dotnet build Encelado.slnx # compilazione
|
||||
dotnet test tests/Encelado.Tests --no-restore # test (xunit)
|
||||
dotnet msbuild build/Release.proj -t:Verifica # compilazione + test nella cartella di verifica
|
||||
dotnet run --project src/Encelado.Server -- [--no-autostart] [--sample] [--port 8080] [--minutes 240] [--bonifica] [--confirm-live "CONFERMO LIVE"] # server locale; comandi da tastiera: status, close, kill, residuo, preset, reset, bonifica, stop
|
||||
scripts\run-dev.ps1 [-Sample] [-Autostart] # server locale nella sandbox deploy/local (= F5 in VS Code); .sh per Git Bash
|
||||
scripts\run-docker.ps1 [-Down] # il container dalla compose, stessa sandbox, token "sviluppo"
|
||||
dotnet run --project src/Encelado.Server -- [--no-autostart] [--sample] [--port 8080] [--minutes 240] [--bonifica] [--listen-all] # server locale; comandi da tastiera: status, close, kill, residuo, reset, bonifica, stop
|
||||
scripts\run-dev.ps1 [-Sample] [-Autostart] # server locale nella sandbox deploy/local, password "sviluppo", solo localhost (= F5 in VS Code); .sh per Git Bash
|
||||
scripts\run-docker.ps1 [-Down] # il container dalla compose, stessa sandbox, password "sviluppo"
|
||||
scripts\screenshots.ps1 # docs/img dal server campione
|
||||
dotnet run --project tools/Encelado.Backtest -- ticks --data "A:\Download\Trading" --out "%USERPROFILE%\Documents\Encelado\data\market"
|
||||
dotnet run --project tools/Encelado.Backtest -- baskets --data "%USERPROFILE%\Documents\Encelado\data\market" --out results
|
||||
dotnet run --project tools/Encelado.Backtest -- falsify --data "%USERPROFILE%\Documents\Encelado\data\market" --out reports [--costs api]
|
||||
dotnet run --project tools/Encelado.Backtest -- learn --data "%USERPROFILE%\Documents\Encelado\data" [--knowledge …] [--strategy config/strategy.json]
|
||||
dotnet run --project tools/Encelado.Backtest -- learn --data "%USERPROFILE%\Documents\Encelado\data" [--knowledge …] [--strategy config/strategy.json] # prende il lock della cartella dati o si rifiuta
|
||||
dotnet msbuild build/Release.proj -t:Docker # immagine 192.168.30.23:3000/alby96/encelado:<v> (test dentro la build)
|
||||
dotnet msbuild build/Release.proj -t:Rilascia -p:Versione=5.0.0 # zip + immagine + tag + push dell'immagine + release su Gitea (dopo il commit e il push del ramo)
|
||||
docker compose up --build # il container in locale (deploy/local/, segreti in .env)
|
||||
dotnet msbuild build/Release.proj -t:Rilascia -p:Versione=5.1.0 # zip + immagine + tag + push dell'immagine + release su Gitea (dopo il commit e il push del ramo)
|
||||
docker compose up --build # il container in locale (deploy/local/, password in .env o "sviluppo")
|
||||
```
|
||||
|
||||
`--sample` lavora in cartelle temporanee, non tocca configurazione, segreti, dati né Telegram, e rifiuta ogni comando o salvataggio. `--listen-all` apre la rete fuori dal container (con la password); nel container la rete è aperta di suo.
|
||||
|
||||
## Regole
|
||||
|
||||
1. **Chiedi se hai un dubbio.** Le domande vanno in `docs/QUESTIONS.md`, numerate, con il default che applicheresti; in assenza di risposta applica il default più prudente e annotalo.
|
||||
2. **Mai un ordine reale senza flag e conferma.** `run.executionMode` predefinito `Demo`; `Live` richiede `run.allowLive = true` **e** la frase `CONFERMO LIVE` (dialogo dell'interfaccia, `--confirm-live`, o `ENCELADO_CONFIRM_LIVE`). Nessuna approvazione per singolo ordine (D-20): il bot opera da solo.
|
||||
2. **Mai un ordine reale senza flag e conferma.** `run.executionMode` predefinito `Demo`; `Live` (il conto reale) richiede `run.allowLive = true` **e** la frase `CONFERMO LIVE` scritta nell'interfaccia a ogni avvio (dialogo di AVVIA) e prima di ogni cambio che riavvia il motore in Live. Il Live non parte mai da solo, né all'avvio del container né dopo un riavvio automatico. Nessuna approvazione per singolo ordine (D-20): il bot opera da solo.
|
||||
3. **Mai una riga del ledger modificata.**
|
||||
4. **Mai un risultato abbellito.** Se la strategia non regge i costi di eToro, il report lo dice con i numeri. "Nessuna configurazione profittevole" è un esito ammesso.
|
||||
5. **Non toccare la catena di rilascio** (`build/`) se non richiesto; è condivisa con Mimante/AutoBidder.
|
||||
6. **Un commit a fine sessione**, dopo che la verifica passa, con un messaggio che dice cosa cambia e perché. Il push lo decide l'utente.
|
||||
7. Aggiorna `docs/STATE.md` e `CHANGELOG.md` a fine sessione; un ADR per ogni scelta non ovvia.
|
||||
7. Aggiorna `docs/STATE.md` e `CHANGELOG.md` a fine sessione; un ADR per ogni scelta non ovvia; `docs/API.md` nello stesso commit di ogni campo cambiato.
|
||||
8. Le skill di progetto in `.claude/skills/` (`encelado-start`, `encelado-verify`, `encelado-diagnose`, `encelado-docs`, `encelado-release`, `encelado-ui`) dicono come si comincia, si verifica, si diagnostica, si chiude e si rilascia: usale.
|
||||
|
||||
## Cose da non fare
|
||||
|
||||
- Non scrivere chiavi in chat, nel log, nel repo, in `Documenti` o nel template Unraid.
|
||||
- Non scrivere chiavi, token o password in chat, nel log, nel repo, in `Documenti` o nel template Unraid.
|
||||
- Non reintrodurre variabili d'ambiente per le impostazioni: tutto passa da Impostazioni e da `secrets.enc` (ADR-0010).
|
||||
- Non usare spread fissi nel cost gate: sempre lo spread reale letto dall'API in quel momento più il markup dell'endpoint dei costi.
|
||||
- Non usare i `proceeds` di una chiusura come P&L: il realizzato viene solo dallo storico eToro (ADR-0011).
|
||||
- Non ricostruire feature a posteriori: il dataset di addestramento è il ledger scritto al momento della decisione.
|
||||
- Non cambiare parametri live in automatico: le proposte passano da `knowledge/proposals.csv` e dal forward test.
|
||||
- Non reintrodurre un'interfaccia desktop né librerie JavaScript: l'interfaccia è servita dal bot ed è vanilla (ADR-0007).
|
||||
- Non chiamare metodi del motore da un altro thread né leggere il suo stato dal web: comandi sul thread di decisione e viste pubblicate (ADR-0012).
|
||||
- Non reintrodurre un'interfaccia desktop né librerie JavaScript: l'interfaccia è servita dal bot ed è vanilla (ADR-0007, ADR-0013).
|
||||
- Non usare heredoc lunghi o con backslash nel Bash tool: usare `Write`/`Edit` (vedi memoria `strumenti-heredoc-backslash`).
|
||||
@@ -18,7 +18,7 @@
|
||||
dal tag git — vedi build/Release.proj — e questo serve solo da seme quando
|
||||
non esiste ancora nessun tag. Tenerlo allineato all'ultimo rilascio evita
|
||||
di leggere a schermo un numero che non corrisponde a niente. -->
|
||||
<Version>5.0.0</Version>
|
||||
<Version>5.1.0</Version>
|
||||
</PropertyGroup>
|
||||
|
||||
<!--
|
||||
|
||||
@@ -7,8 +7,12 @@
|
||||
# non trimmed: il server ospita ASP.NET Core minimal e non è AOT). Il runtime è
|
||||
# l'immagine ufficiale aspnet, con gosu per scendere ai PUID/PGID di Unraid.
|
||||
#
|
||||
# docker build -t 192.168.30.23:3000/alby96/encelado:5.0.0 --build-arg GIT_COMMIT=$(git rev-parse --short=12 HEAD) .
|
||||
# docker run -p 8080:8080 -v ./config:/config -v ./data:/data -e TZ=Europe/Rome 192.168.30.23:3000/alby96/encelado:5.0.0
|
||||
# docker build -t 192.168.30.23:3000/alby96/encelado:5.1.0 --build-arg GIT_COMMIT=$(git rev-parse --short=12 HEAD) .
|
||||
# docker run -p 8080:8080 -v ./config:/config -v ./data:/data -e ENCELADO_PASSWORD=… 192.168.30.23:3000/alby96/encelado:5.1.0
|
||||
#
|
||||
# L'unica variabile da dare al container è ENCELADO_PASSWORD (la password
|
||||
# dell'interfaccia): tutto il resto si imposta dall'interfaccia. Le ENV qui sotto sono
|
||||
# interne all'immagine (PUID/PGID/TZ restano i default di Unraid e UTC).
|
||||
#
|
||||
# Vedi docs/DOCKER.md per volumi, variabili, healthcheck e aggiornamento.
|
||||
|
||||
@@ -62,7 +66,6 @@ RUN apt-get update \
|
||||
|
||||
ENV ENCELADO_IN_CONTAINER=1 \
|
||||
ENCELADO_WEB_PORT=8080 \
|
||||
ENCELADO_AUTOSTART=1 \
|
||||
DOTNET_gcServer=1 \
|
||||
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 \
|
||||
ASPNETCORE_URLS= \
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Encelado
|
||||
|
||||
Bot di trading **Correlation Baskets** su eToro (Public API): cinque basket di due coppie forex correlate, ingresso quando il cross sintetico diverge (z-score), uscita quando converge o al take-profit di basket, stop di basket obbligatorio, cost gate sullo spread reale, ledger completo, calendario e notizie gratuiti, apprendimento in ombra. Dalla 5.0 gira **solo in un container** e si guarda dal browser.
|
||||
Bot di trading **Correlation Baskets** su eToro (Public API): cinque basket di due coppie forex correlate, ingresso quando il cross sintetico diverge (z-score), uscita quando converge o al take-profit di basket, stop di basket obbligatorio, cost gate sullo spread reale, ledger completo, calendario e notizie gratuiti, apprendimento in ombra. Gira **solo in un container** e si guarda e si configura dal browser. Versione 5.1.0.
|
||||
|
||||
> Il backtest è negativo: la strategia non regge i costi di eToro (`docs/STRATEGY.md`). Il bot è uno strumento di forward test in Demo, non un sistema da mettere sul reale.
|
||||
|
||||
@@ -10,37 +10,49 @@ Bot di trading **Correlation Baskets** su eToro (Public API): cinque basket di d
|
||||
|
||||
```powershell
|
||||
docker pull 192.168.30.23:3000/alby96/encelado:latest
|
||||
docker run -d --name encelado --restart unless-stopped -p 8080:8080 `
|
||||
docker run -d --name encelado --restart unless-stopped --stop-timeout 45 -p 8080:8080 `
|
||||
-v /mnt/user/appdata/encelado/config:/config -v /mnt/user/appdata/encelado/data:/data `
|
||||
-e ENCELADO_WEB_TOKEN=<una-stringa-lunga> -e TZ=Europe/Rome `
|
||||
-e ETORO_API_KEY=<x-api-key> -e ETORO_USER_KEY=<x-user-key> `
|
||||
-e ENCELADO_PASSWORD=<una-frase-lunga> `
|
||||
192.168.30.23:3000/alby96/encelado:latest
|
||||
```
|
||||
|
||||
Poi `http://<ip>:8080/`, token una volta, **AVVIA**. Su Unraid: template in `deploy/unraid/` (icona, porte, volumi e variabili già descritti). Tutto il resto in `docs/DOCKER.md`.
|
||||
L'unica cosa da dare al container è la **password dell'interfaccia** (`ENCELADO_PASSWORD`). Poi:
|
||||
|
||||
Senza token il server ascolta solo su localhost del container. La modalità `Live` richiede `run.allowLive = true`, `ETORO_ENVIRONMENT=real` e la frase `CONFERMO LIVE` in `ENCELADO_CONFIRM_LIVE`.
|
||||
1. apri `http://<ip>:8080/` e scrivi la password;
|
||||
2. **Impostazioni ▸ Conto**: incolla le chiavi eToro del conto demo (`x-api-key`, `x-user-key`) e premi **Verifica e salva** — vengono provate su eToro e salvate cifrate con la password in `/config/secrets.enc`; lì si sceglie anche il conto (Demo o Live) e si inseriscono le chiavi del reale;
|
||||
3. se vuoi Telegram, **Impostazioni ▸ Notifiche Telegram** (token, chat, messaggio di prova);
|
||||
4. **AVVIA** (⏻ in alto a destra).
|
||||
|
||||
Ogni impostazione si cambia dalla pagina e il bot la applica subito, riavviando il motore da sé (senza chiudere i basket) solo quando serve. Il conto reale (`Live`) chiede «Consenti il conto reale» e la frase `CONFERMO LIVE` scritta a ogni avvio, e non parte mai da solo. Senza password il server ascolta solo su localhost del container. Su Unraid: template in `deploy/unraid/` (porta, volumi e password), con la guida all'installazione e all'aggiornamento da un container 5.0 (che ha più variabili: vengono importate una volta e poi si tolgono). Tutto il resto in `docs/DOCKER.md` e `docs/RUNBOOK.md`.
|
||||
|
||||
## Le pagine
|
||||
|
||||
La dashboard riassume tutto in una schermata; ogni altra pagina approfondisce una parte (regole e componenti in `docs/UI_GUIDELINES.md`, dati in `docs/API.md`).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
|  |  |
|
||||
| **Storico ordini**: ordini (unità richieste ed eseguite, slippage, esito), posizioni classificate `basket` / `orfana-bot` / `esterna` / `movimento di cassa`, profitti per periodo con la curva dell'equity, esportazione CSV. | **Log** con filtro, ricerca e «Segui». |
|
||||
|  |  |
|
||||
| **Impostazioni**: configurazione validata, chiavi eToro cifrate, ripristino in cinque passi, Ricerca (modello in ombra, ciclo di apprendimento), Diagnostica (percorsi, quote, bonifica), Informazioni (versione, build, commit). | Sotto i 600 px il rail diventa un menu e i basket diventano cards. |
|
||||
|  |  |
|
||||
| **Basket**: i cinque basket con ogni numero, il grafico dello z e il pannello di dettaglio (stato e soglie, posizione, segnale, contesto, ML, ultime decisioni). | **Posizioni**: ogni posizione del conto classificata `basket` / `orfana-bot` / `esterna`, bonifica delle orfane, ordini in attesa di esito. |
|
||||
|  |  |
|
||||
| **Mercato**: quotazioni e spread, calendario con filtri, sentiment per valuta, notizie, cambi, volatilità. | **Storico**: ordini, posizioni, profitti per periodo con la curva del realizzato, esportazione CSV. |
|
||||
|  |  |
|
||||
| **Apprendimento**: dataset, criteri di attivazione, pesi imparati, bandit dei preset, ultimo ciclo, calibrazione, proposte. | **Log**: una riga per messaggio con il livello colorato, filtro, ricerca e «Segui». |
|
||||
|  |  |
|
||||
| **Sistema**: motore, collegamento eToro e quote, feed, Telegram, segreti, processo, disco. | **Impostazioni**: tutto si imposta da qui e il bot lo applica senza riavvio quando può; chiavi e token cifrati. |
|
||||
|  |  |
|
||||
| Tema chiaro con gli stessi token. | Sotto i 480 px il menu si apre dal bottone ☰. |
|
||||
|
||||
## Provarlo in locale
|
||||
|
||||
Tre modi, tutti sulla stessa sandbox `deploy/local/` (ignorata da git: `config/` è il `/config` del container, `data/` il `/data`), così configurazione e chiavi salvate valgono ovunque:
|
||||
Tre modi, tutti sulla stessa sandbox `deploy/local/` (ignorata da git: `config/` è il `/config` del container, `data/` il `/data`) e con la stessa password `sviluppo`, così configurazione e segreti salvati valgono ovunque:
|
||||
|
||||
| Modo | Come | Cosa ottieni |
|
||||
|---|---|---|
|
||||
| **F5 in VS Code** | configurazione `Encelado (server)` | server locale su `http://localhost:8080/`, browser aperto da solo, motore fermo finché non premi **AVVIA**; `Encelado (campione)` mostra le pagine con dati finti senza chiavi |
|
||||
| **F5 in VS Code** | configurazione `Encelado (server)` | server locale su `http://localhost:8080/` (solo localhost), browser aperto da solo, motore fermo finché non premi **AVVIA**; `Encelado (campione)` mostra le pagine con dati d'esempio, senza chiavi, in cartelle temporanee |
|
||||
| **Script** | `scripts\run-dev.ps1` (`-Sample`, `-Autostart`, `-Port`) o `sh scripts/run-dev.sh` | lo stesso processo da terminale, con i comandi da tastiera (`status`, `kill`, `stop`…) |
|
||||
| **Container** | `scripts\run-docker.ps1` (o `sh scripts/run-docker.sh`, o `docker compose up -d --build`) | l'immagine vera su `http://localhost:8080/`, token `sviluppo`; `-Down` per fermare con SIGTERM |
|
||||
| **Container** | `scripts\run-docker.ps1` (o `sh scripts/run-docker.sh`, o `docker compose up -d --build`) | l'immagine vera su `http://localhost:8080/`, password `sviluppo` (o `ENCELADO_PASSWORD` in `.env`); `-Down` per fermare con SIGTERM |
|
||||
|
||||
Le chiavi eToro: variabili `ETORO_API_KEY`/`ETORO_USER_KEY` nell'ambiente (per il compose in un file `.env` accanto alla `docker-compose.yml`), oppure **Impostazioni ▸ Chiavi eToro** nella pagina con `ENCELADO_KEY_PASSPHRASE` impostata (vengono verificate e salvate cifrate in `deploy/local/config/etoro.keys.enc`). Senza chiavi il motore non parte e la pagina lo dice; lo storico mostra solo il ledger.
|
||||
Le chiavi eToro si inseriscono da **Impostazioni ▸ Conto** (una scheda per il conto demo e una per il reale): vengono verificate e salvate cifrate in `deploy/local/config/secrets.enc`, leggibili da tutti e tre i modi perché la password è la stessa. Senza chiavi il motore non parte e la pagina lo dice; lo storico mostra solo il ledger. Fuori dal container il server resta su localhost anche con la password (per la rete: `--listen-all`).
|
||||
|
||||
```powershell
|
||||
dotnet build Encelado.slnx # compilazione
|
||||
@@ -56,13 +68,13 @@ Attività di VS Code: `verifica`, `backtest`, `avvia in locale (script)`, `avvia
|
||||
src/Encelado.Core logica pura: basket, cross sintetici, decisore, cost gate, sizing, esecutore, registro ordini, kill-switch, apprendimento, notifiche
|
||||
src/Encelado.Etoro client HTTP di eToro Public API
|
||||
src/Encelado.Engine motore, ledger, feed, configurazione, impostazioni, storico, Telegram
|
||||
src/Encelado.Server l'eseguibile: Kestrel, API JSON, SSE, interfaccia incorporata (Material 3, vanilla)
|
||||
src/Encelado.Server l'eseguibile: Kestrel, API JSON, SSE, interfaccia incorporata (moduli ES vanilla, nessuna libreria)
|
||||
tools/Encelado.Backtest ticks, baskets, falsify, learn
|
||||
tests/Encelado.Tests xunit
|
||||
deploy/ docker (entrypoint), unraid (template), local (ignorato: sandbox di F5 e del compose)
|
||||
scripts/ run-dev, run-docker, screenshots (.ps1 e .sh)
|
||||
build/ catena di verifica, pacchetto e rilascio (MSBuild)
|
||||
docs/ STATE, ARCHITECTURE, STRATEGY, RUNBOOK, DOCKER, UI_GUIDELINES, ADR…
|
||||
docs/ STATE, ARCHITECTURE, API, STRATEGY, RUNBOOK, DOCKER, UI_GUIDELINES, ADR…
|
||||
```
|
||||
|
||||
Leggi `CLAUDE.md` per le convenzioni e `docs/STATE.md` per lo stato del lavoro.
|
||||
|
||||
@@ -1,39 +1,38 @@
|
||||
{
|
||||
"_commento": "Configurazione di Encelado — Correlation Baskets su eToro (CFD forex). Le chiavi con il prefisso _ sono documentazione e vengono ignorate. I parametri della strategia (basket, preset, soglie, rischio) stanno in strategy.json accanto a questo file. Le chiavi API non stanno qui: si inseriscono dalla finestra e vivono cifrate in %LOCALAPPDATA%\\Encelado\\etoro.dat, oppure nelle variabili d'ambiente ETORO_API_KEY e ETORO_USER_KEY.",
|
||||
"_commento": "Configurazione di Encelado — Correlation Baskets su eToro (CFD forex). Si modifica da Impostazioni nell'interfaccia web, che applica subito tutto quello che può (quando serve riavvia il motore da sé, senza chiudere i basket). Le chiavi con il prefisso _ sono documentazione e vengono ignorate. I parametri della strategia (basket, preset, soglie, rischio) stanno in strategy.json accanto a questo file. Le chiavi eToro e il token Telegram non stanno qui: si inseriscono da Impostazioni e vivono cifrati in secrets.enc con la password dell'interfaccia.",
|
||||
|
||||
"etoro": {
|
||||
"_note": "eToro Public API. environment = demo oppure real: chiavi e rotte sono diverse, e l'ambiente attivo è sempre visibile nella finestra.",
|
||||
"environment": "demo",
|
||||
"_note": "eToro Public API. Il conto segue run.executionMode: Demo = conto demo, Live = conto reale; chiavi e rotte dei due conti sono diverse e il conto attivo è sempre visibile nell'interfaccia.",
|
||||
"baseUrl": "https://public-api.etoro.com",
|
||||
"_requestTimeoutSeconds": "Oltre questo tempo una richiesta HTTP a eToro viene abbandonata (e, se era una lettura, ritentata).",
|
||||
"requestTimeoutSeconds": 20,
|
||||
"_fillTimeoutSeconds": "Quanto attendere l'esito di un ordine (eToro lo lavora in modo asincrono) prima di trattarlo come non confermato e riconciliare. È anche il timeout della seconda gamba (leg-risk).",
|
||||
"fillTimeoutSeconds": 5
|
||||
},
|
||||
|
||||
"run": {
|
||||
"_executionMode": "Paper = simulatore locale sopra le quotazioni reali (nessun ordine sul conto). Demo = conto demo di eToro: ordini veri, denaro virtuale, il bot apre e chiude da solo. Live = conto reale: richiede allowLive = true e la frase CONFERMO LIVE a ogni avvio. Nessuna modalità chiede l'approvazione dei singoli ordini (decisione D-20).",
|
||||
"_executionMode": "Demo = conto demo di eToro: ordini veri, denaro virtuale, il bot apre e chiude da solo. Live = conto reale: richiede allowLive = true e la frase CONFERMO LIVE scritta nell'interfaccia a ogni avvio; in Live il motore non parte mai da solo. Il cambio di conto è rifiutato finché ci sono basket aperti o ordini in sospeso. Nessuna modalità chiede l'approvazione dei singoli ordini (decisione D-20).",
|
||||
"executionMode": "Demo",
|
||||
"allowLive": false,
|
||||
"_autostart": "true = all'avvio del container il motore parte da solo (mai in Live, che aspetta AVVIA con la frase). false = il motore parte solo con AVVIA.",
|
||||
"autostart": true,
|
||||
"_pollSeconds": "Secondi fra due letture delle quotazioni (una richiesta per tutti gli strumenti). 3 s = 20 richieste al minuto su una quota di 120: resta spazio per candele e costi.",
|
||||
"pollSeconds": 3,
|
||||
"_statusSeconds": "Ogni quanti secondi il bot scrive una riga di stato nel log (e sulla console in headless).",
|
||||
"_statusSeconds": "Ogni quanti secondi il bot scrive una riga di stato nel log (e sulla console).",
|
||||
"statusSeconds": 60,
|
||||
"_closeOnShutdown": "true = fermare il bot chiude i basket aperti a mercato. false = restano sul conto con gli stop nativi sul server, senza nessuno che applichi il take-profit o lo stop di basket finché il bot non riparte.",
|
||||
"_closeOnShutdown": "true = fermare il bot chiude i basket aperti a mercato. false = restano sul conto con gli stop nativi sul server, senza nessuno che applichi il take-profit o lo stop di basket finché il bot non riparte. Un riavvio automatico dopo un cambio delle impostazioni non chiude mai niente.",
|
||||
"closeOnShutdown": false,
|
||||
"strategyFile": "strategy.json",
|
||||
"_cartelle": "Relative alla cartella di questo file: data (mercato, calendario, notizie, ledger, modelli), knowledge (calibrazione, proposte, registri), reports.",
|
||||
"_cartelle": "Relative alla cartella di questo file: data (mercato, calendario, notizie, ledger, modelli), knowledge (calibrazione, proposte, registri), reports. Nel container stanno in /data.",
|
||||
"dataDirectory": "data",
|
||||
"knowledgeDirectory": "knowledge",
|
||||
"reportsDirectory": "reports",
|
||||
"_paper": "Solo per executionMode = Paper: saldo iniziale del simulatore e slippage per gamba oltre lo spread reale del momento.",
|
||||
"paperStartingBalance": 10000,
|
||||
"paperSlippagePips": 0.3
|
||||
"reportsDirectory": "reports"
|
||||
},
|
||||
|
||||
"ui": {
|
||||
"_timeZone": "Fuso orario con cui l'interfaccia mostra gli orari. 'computer' = quello del sistema (nel container la variabile TZ); 'UTC'; oppure un id IANA (es. 'Europe/Rome'). Il file di log porta l'offset, il ledger è in UTC: cambiare questo valore non tocca nessun file.",
|
||||
"_timeZone": "Fuso degli orari scritti dal server (righe di attività, riga di stato): 'computer' = quello del sistema; 'UTC'; oppure un id IANA (es. 'Europe/Rome'). Gli orologi dell'interfaccia usano il fuso del browser; il file di log porta l'offset e il ledger è in UTC.",
|
||||
"timeZone": "computer",
|
||||
"_displayCurrency": "Valuta in cui l'interfaccia, Telegram e le esportazioni mostrano gli importi (USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD). I tassi vengono dalle quotazioni eToro già in polling; ledger e decisioni restano in USD. Anche ENCELADO_DISPLAY_CURRENCY.",
|
||||
"_displayCurrency": "Valuta in cui l'interfaccia mostra gli importi (USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD). I tassi vengono dalle quotazioni eToro già in polling; ledger e decisioni restano in USD.",
|
||||
"displayCurrency": "USD",
|
||||
"_theme": "dark oppure light.",
|
||||
"theme": "dark",
|
||||
@@ -57,7 +56,7 @@
|
||||
},
|
||||
|
||||
"notifications": {
|
||||
"_telegram": "Notifiche e comandi su Telegram (5.0). Il token del bot NON si scrive qui: variabile d'ambiente TELEGRAM_BOT_TOKEN (e TELEGRAM_CHAT_ID, che ha la precedenza su chatId). hourlyStatus = stato allo scoccare di ogni ora UTC; eventAlerts = aperture, chiusure, ordini risolti, kill-switch, recupero, errori; dailySummaryUtcHour = ora UTC del riepilogo giornaliero (negativo = spento); commands = risposte ai comandi /stato, /posizioni, /storico, /pausa, /riprendi, /chiudi, /kill CONFERMO, /reset dalla sola chat autorizzata.",
|
||||
"_telegram": "Notifiche e comandi su Telegram. Il token del bot si inserisce da Impostazioni ▸ Notifiche Telegram e vive cifrato in secrets.enc, mai in questo file; chatId è la sola chat che riceve i messaggi e può dare comandi. hourlyStatus = stato allo scoccare di ogni ora UTC; eventAlerts = aperture, chiusure, ordini risolti, kill-switch, recupero, errori; dailySummaryUtcHour = ora UTC del riepilogo giornaliero (negativo = spento); commands = risposte ai comandi /stato, /posizioni, /storico, /pausa, /riprendi, /chiudi, /kill CONFERMO, /reset dalla sola chat autorizzata.",
|
||||
"telegram": {
|
||||
"enabled": false,
|
||||
"chatId": "",
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
{
|
||||
"_comment": "Encelado — strategia Correlation Baskets su eToro. Cinque basket di due coppie forex correlate: si entra quando il cross sintetico diverge (z-score), si esce quando converge o al take-profit di basket in pip; lo stop di basket è obbligatorio. Ogni chiave con '_' davanti è documentazione.",
|
||||
|
||||
"_preset": "Conservative | Moderate | Aggressive. Fissa zIn, riskPerBasketPct, maxBaskets, tpPips, maxAdds, zStop; si cambia a caldo dalla finestra senza toccare i basket aperti. Le chiavi omonime qui sotto, se presenti, sovrascrivono il preset.",
|
||||
"_preset": "Conservative | Moderate | Aggressive. Fissa zIn, riskPerBasketPct, maxBaskets, tpPips, maxAdds, zStop. Si sceglie in Impostazioni ▸ Strategia e il bot lo applica subito ai basket nuovi: quelli già aperti tengono take-profit, perdita massima, zStop e aggiunte con cui sono entrati. Le chiavi omonime qui sotto, se presenti, sovrascrivono il preset.",
|
||||
"preset": "Moderate",
|
||||
|
||||
"_signalMode": "ZScoreSynthetic (default, |z| >= zIn sul cross sintetico) oppure PipDivergence (fedele all'interfaccia Titany: divergenza in pip dall'ancora, dIn).",
|
||||
"signalMode": "ZScoreSynthetic",
|
||||
"_exitMode": "First = la prima fra TP in pip e rientro dello z; FixedPips = solo TP in pip lordi; ZReturn = solo |z| <= zOut.",
|
||||
"exitMode": "First",
|
||||
"_averagingMode": "Off | AddOnce | Grid. Off in live; AddOnce in paper. Moltiplicatore di lotto sempre 1,0 (niente martingala).",
|
||||
"_averagingMode": "Off | AddOnce | Grid. Off di fabbrica; AddOnce ammette una sola aggiunta per basket, Grid fino a maxAdds. Moltiplicatore di lotto sempre 1,0 (niente martingala).",
|
||||
"averagingMode": "Off",
|
||||
"tpMode": "Pips",
|
||||
"_sameCrossPolicy": "I basket 4 e 5 sono entrambi EURCAD: Exclusive = uno solo aperto per volta; Half = entrambi a metà size.",
|
||||
@@ -63,13 +63,13 @@
|
||||
"volAverageDays": 30,
|
||||
"mlMinProbability": 0.55,
|
||||
|
||||
"_sicurezza": "equityStopPct: perdita dal picco di equity (al netto dei movimenti di cassa) oltre la quale il bot chiude tutto e si blocca (reset manuale con motivazione). dailyLossPct: perdita giornaliera oltre la quale niente nuove entrate fino al giorno dopo.",
|
||||
"_sicurezza": "equityStopPct: perdita dal picco di equity (al netto dei movimenti di cassa) oltre la quale il bot chiude tutto e si blocca (reset manuale con motivazione). dailyLossPct: perdita giornaliera oltre la quale niente nuove entrate fino alle 00:00 UTC, anche se poi l'equity recupera.",
|
||||
"equityStopPct": 9,
|
||||
"dailyLossPct": 3,
|
||||
"legTimeoutSec": 5,
|
||||
"clockSkewMaxSeconds": 5,
|
||||
|
||||
"_risk": "Margine (5.0, §10). La size di un basket è il minimo fra la size a rischio e quella a margine. maxMarginUsePct: margine totale impegnato dopo l'apertura, in % dell'equity. maxMarginPerBasketPct: margine delle due gambe di un basket, in % dell'equity. marginBufferPct: il disponibile deve superare il margine richiesto di questa percentuale prima di inviare A e, ricontrollato, prima di inviare B (altrimenti A viene richiusa). closeForeignOnKill: il kill-switch chiude anche le posizioni non aperte dal bot. marginCallBlockRatio / marginCallCloseRatio: sotto equity/margine usato = 1,5 niente entrate; sotto 1,2 si chiude il basket con il P&L peggiore.",
|
||||
"_risk": "Margine (5.0, §10). La size di un basket è il minimo fra la size a rischio e quella a margine. maxMarginUsePct: margine totale impegnato dopo l'apertura, in % dell'equity. maxMarginPerBasketPct: margine delle due gambe di un basket, in % dell'equity. marginBufferPct: il disponibile deve superare il margine richiesto di questa percentuale prima di inviare A e, ricontrollato, prima di inviare B (altrimenti A viene richiusa). closeForeignOnKill: il kill-switch chiude anche le posizioni non aperte dal bot (Telegram /kill, file STOP); nel dialogo del kill-switch è solo la scelta di partenza della casella. marginCallBlockRatio / marginCallCloseRatio: sotto equity/margine usato = 1,5 niente entrate; sotto 1,2 si chiude il basket con il P&L peggiore.",
|
||||
"risk": {
|
||||
"maxMarginUsePct": 40,
|
||||
"maxMarginPerBasketPct": 12,
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
# Encelado su Unraid
|
||||
|
||||
Il template `encelado.xml` installa il container dall'immagine sul registro di Gitea
|
||||
(`192.168.30.23:3000/alby96/encelado:latest`). Dettagli su volumi, variabili, healthcheck e
|
||||
aggiornamento in `docs/DOCKER.md`; guida operativa in `docs/RUNBOOK.md`.
|
||||
(`192.168.30.23:3000/alby96/encelado:latest`). Dalla 5.1 il container ha **una sola
|
||||
variabile**, la password dell'interfaccia: conto, chiavi eToro, Telegram e ogni altra
|
||||
impostazione si fanno dalla pagina. Dettagli su volumi, variabili, healthcheck e rete in
|
||||
`docs/DOCKER.md`; guida operativa in `docs/RUNBOOK.md`.
|
||||
|
||||
## 1. Il registro di Gitea è in HTTP: dillo a Docker di Unraid
|
||||
|
||||
@@ -36,34 +38,106 @@ Lo stesso file è allegato a ogni release su Gitea con la versione nel nome.
|
||||
| Campo | Cosa mettere |
|
||||
|---|---|
|
||||
| **Porta web** | `8080` (o un'altra libera: la WebUI del container la segue) |
|
||||
| **/config**, **/data** | lascia i default `/mnt/user/appdata/encelado/config` e `/data` |
|
||||
| **ENCELADO_WEB_TOKEN** | **obbligatorio**: una stringa lunga a piacere. Senza, il server ascolta solo dentro il container e dalla rete non si vede niente |
|
||||
| **ETORO_API_KEY**, **ETORO_USER_KEY** | le chiavi del conto **demo** (dal portale sviluppatori eToro; demo e reale hanno chiavi diverse). Oppure lasciale vuote e inseriscile poi dall'interfaccia, mettendo una **ENCELADO_KEY_PASSPHRASE** |
|
||||
| **ETORO_ENVIRONMENT** | `demo` |
|
||||
| **ENCELADO_EXECUTION_MODE** | `Demo` |
|
||||
| **TZ** | `Europe/Rome` |
|
||||
| **TELEGRAM_BOT_TOKEN**, **TELEGRAM_CHAT_ID** | facoltativi: notifiche ogni ora, eventi, riepilogo serale e comandi dalla chat |
|
||||
| PUID / PGID | `99` / `100` (nobody:users, i default di Unraid) |
|
||||
| **Configurazione (/config)**, **Dati (/data)** | lascia i default `/mnt/user/appdata/encelado/config` e `/mnt/user/appdata/encelado/data` |
|
||||
| **Password interfaccia** (`ENCELADO_PASSWORD`) | **obbligatoria**: una frase lunga a piacere. Apre l'interfaccia e cifra le chiavi eToro e il token Telegram che salverai dalla pagina. Senza, il server ascolta solo dentro il container e dalla rete non si vede niente |
|
||||
|
||||
`ENCELADO_CONFIRM_LIVE` resta vuoto: serve solo per il conto reale, che oggi non è praticabile.
|
||||
Non serve altro: niente chiavi, ambiente, modalità, `TZ`, `PUID`/`PGID` (l'immagine usa
|
||||
99/100, `nobody:users`; `TZ` lo aggiunge Unraid da sé e vale solo per gli orari mostrati dal
|
||||
server e per il log).
|
||||
|
||||
## 4. Primo avvio
|
||||
|
||||
1. **Apply**. Il container semina `encelado.json` e `strategy.json` in `/mnt/user/appdata/encelado/config`.
|
||||
2. Apri `http://<ip-unraid>:8080/`, inserisci il token (resta in un cookie per trenta giorni).
|
||||
3. Se non hai messo le chiavi nelle variabili: **Impostazioni ▸ Chiavi eToro ▸ Verifica e salva** (vengono provate contro eToro e salvate cifrate in `/config/etoro.keys.enc`).
|
||||
4. Con `ENCELADO_AUTOSTART` al default (`1`) il motore è già partito; altrimenti **AVVIA**. Il chip in basso a sinistra dice `DEMO`.
|
||||
5. Per un test lungo guarda: contatore «in attesa · orfane · esterne» (orfane deve restare 0), **Storico ▸ Ordini** (unità richieste ed eseguite uguali, esito `Filled`), il log. Il kill-switch è il pulsante in alto a destra, o un file `STOP` in `/mnt/user/appdata/encelado/config`.
|
||||
2. Apri `http://<ip-unraid>:8080/` e scrivi la password (resta in un cookie per trenta giorni).
|
||||
3. **Impostazioni ▸ Conto**: il conto è `Demo`. Nella scheda delle chiavi del conto demo incolla
|
||||
`x-api-key` e `x-user-key` (dal portale sviluppatori eToro; demo e reale hanno chiavi
|
||||
diverse) e premi **Verifica e salva**: vengono provate su quel conto e salvate cifrate in
|
||||
`/config/secrets.enc`.
|
||||
4. Facoltativo: **Impostazioni ▸ Notifiche Telegram** (token del bot, chat, notifiche, comandi;
|
||||
**Invia messaggio di prova**), valuta e tema in Interfaccia, preset in Strategia.
|
||||
5. Premi **AVVIA** (⏻ in alto a destra). La pill del motore nella barra in alto dice `DEMO`. Con
|
||||
«Avvio automatico» acceso (di fabbrica) ai riavvii successivi il motore parte da solo.
|
||||
6. Per un test lungo guarda: contatori di Posizioni (le orfane devono restare 0), **Storico ▸
|
||||
Ordini** (unità richieste ed eseguite uguali, esito `Filled`), il Log. Il kill-switch è
|
||||
**KILL** in alto a destra, o un file `STOP` in `/mnt/user/appdata/encelado/config`.
|
||||
|
||||
Il log è in `docker logs encelado` e in `/mnt/user/appdata/encelado/data/logs/encelado.log`; il ledger in `.../data/data/ledger/`.
|
||||
Il log è in `docker logs encelado` e in `/mnt/user/appdata/encelado/data/logs/encelado.log`; il
|
||||
ledger in `.../data/data/ledger/`.
|
||||
|
||||
## 5. Aggiornamento
|
||||
Le chiavi e il token si cambiano **sempre dalla pagina** (Impostazioni ▸ Conto, Notifiche
|
||||
Telegram), anche più avanti: una variabile come `ETORO_API_KEY` aggiunta al container viene
|
||||
ignorata (e segnalata), e il bot continuerebbe con le chiavi vecchie.
|
||||
|
||||
## 5. Aggiornare un container 5.0 alla 5.1
|
||||
|
||||
Il container 5.0 ha una dozzina di variabili (chiavi eToro, `ETORO_ENVIRONMENT`,
|
||||
`ENCELADO_EXECUTION_MODE`, `ENCELADO_WEB_TOKEN`, Telegram, `TZ`, `PUID`/`PGID`…). La 5.1 le
|
||||
legge **una volta sola**, al primo avvio, e poi le ignora. Quindi:
|
||||
|
||||
1. **Prima di aggiornare non togliere niente.** Le variabili servono al primo avvio della 5.1
|
||||
per portare chiavi, token, chat e impostazioni nel posto nuovo. Se le chiavi erano salvate
|
||||
dall'interfaccia della 5.0 (`/config/etoro.keys.enc`), lascia anche `ENCELADO_KEY_PASSPHRASE`.
|
||||
Facoltativo ma consigliato: una copia di `/mnt/user/appdata/encelado`.
|
||||
2. **Rinomina la password**: *Docker ▸ Encelado ▸ Edit*, sul campo `ENCELADO_WEB_TOKEN` premi
|
||||
*Edit* e cambia la **Key** in `ENCELADO_PASSWORD`, **con lo stesso valore** (e *Password
|
||||
Mask* acceso). La password dell'interfaccia resta quella di prima e i segreti che la 5.1
|
||||
cifrerà con lei restano leggibili. (Anche lasciandola com'è la 5.1 parte: `ENCELADO_WEB_TOKEN`
|
||||
vale come alias deprecato, con un avviso.)
|
||||
3. **Apply**: Unraid scarica `:latest` (la 5.1) e riavvia il container. Al primo avvio la 5.1:
|
||||
- importa le variabili e i file della 5.0 (`docker logs encelado`: «importazione una tantum
|
||||
dalla 5.0: …»; il resoconto resta in `/config/import-5.1.json`); il vecchio
|
||||
`etoro.keys.enc` diventa `etoro.keys.enc.migrato`;
|
||||
- sposta lo stato del motore nel file del suo conto (`baskets_state.json` →
|
||||
`baskets_state.demo.json` o `.live.json`; l'originale resta come `.migrato`) e riprende i
|
||||
basket aperti. Il conto è quello su cui lavorava la 5.0 (con `ENCELADO_EXECUTION_MODE=Live`
|
||||
e `ETORO_ENVIRONMENT=demo` era il conto demo): per questo al primo avvio le variabili vanno
|
||||
lasciate come sono. Lo stato della modalità Paper non viene ripreso (il log dice «non
|
||||
ripreso: …»);
|
||||
- verifica sullo storico eToro il P&L delle righe scritte dalla 4.0.0-5.0.0 (che erano i
|
||||
proceeds delle chiusure, non il profitto) e scrive righe di correzione; se ne ha corrette,
|
||||
mette da parte una volta i modelli addestrati su quei numeri.
|
||||
4. Apri la pagina con la **stessa password** (serve un nuovo accesso: il cookie della 5.1 contiene
|
||||
anche un segreto del server, `/config/session.key`, creato ora). Controlla **Sistema ▸ Segreti** (chiavi del conto
|
||||
demo, ed eventualmente reale, presenti; la nota dell'importazione) e la striscia sotto la
|
||||
barra in alto: «Variabili d'ambiente ignorate: …» elenca quelle da togliere.
|
||||
5. *Edit* di nuovo e **togli tutte le variabili tranne `ENCELADO_PASSWORD`**: `ETORO_API_KEY`,
|
||||
`ETORO_USER_KEY`, `ETORO_ENVIRONMENT`, `ENCELADO_EXECUTION_MODE`, `ENCELADO_KEY_PASSPHRASE`,
|
||||
`ENCELADO_CONFIRM_LIVE`, `ENCELADO_AUTOSTART`, `ENCELADO_DISPLAY_CURRENCY`,
|
||||
`ENCELADO_LOG_LEVEL`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, e anche i campi `TZ`,
|
||||
`PUID` e `PGID` del template vecchio (l'immagine usa già 99/100 e Unraid aggiunge `TZ` da
|
||||
sé). **Apply**: la striscia non elenca più niente.
|
||||
6. Nella pagina **Apprendimento** premi **Esegui ciclo**, per rifare calibrazione e intuizioni
|
||||
sulle etichette corrette.
|
||||
|
||||
Se a un certo punto la password **cambia** (un valore diverso da quello della 5.0), la pagina
|
||||
si apre con la nuova ma i segreti risultano **bloccati** (striscia rossa «SEGRETI BLOCCATI»,
|
||||
il motore non parte): in **Impostazioni ▸ Conto** scegli **Sblocca con la password
|
||||
precedente** e scrivi quella vecchia (i segreti vengono ricifrati con la nuova), oppure
|
||||
**Ricomincia** (il deposito vecchio resta come `secrets.enc.<data>.bak`) e reinserisci chiavi e
|
||||
token.
|
||||
|
||||
Se il container 5.0 lavorava in **Live**: la 5.1 non parte mai da sola sul conto reale. Dopo
|
||||
l'aggiornamento (e dopo ogni riavvio) premi **AVVIA** e scrivi `CONFERMO LIVE`; nel frattempo i
|
||||
basket aperti hanno solo gli stop nativi. Dalla 5.1 la modalità è anche il conto: un file o
|
||||
delle variabili della 5.0 valgono Live solo se dicevano modalità `Live` **e** ambiente `real`
|
||||
(il Live delle variabili viene importato solo con «Consenti il conto reale» acceso);
|
||||
altrimenti la 5.1 lavora sul conto demo e il log dice perché.
|
||||
|
||||
## 6. Aggiornamenti successivi
|
||||
|
||||
*Docker ▸ Check for Updates*: il tag `latest` segue l'ultima release. Il container si ferma
|
||||
con SIGTERM (45 s di grazia): i basket aperti restano sul conto con gli stop nativi e
|
||||
vengono ripresi dallo stato salvato e dalla riconciliazione al riavvio (`docs/RUNBOOK.md`,
|
||||
«Recupero dopo inattività»). Per tornare a una versione precisa cambia il tag nel campo
|
||||
**Repository** (`…/encelado:5.0.0`).
|
||||
vengono ripresi dallo stato del conto e dalla riconciliazione al riavvio (`docs/RUNBOOK.md`,
|
||||
«Recupero dopo inattività»); un kill-switch in corso ha 30 s per finire. Per tornare a una
|
||||
versione precisa cambia il tag nel campo **Repository** (`…/encelado:5.1.0`).
|
||||
|
||||
## Reverse proxy
|
||||
|
||||
Se metti l'interfaccia dietro un reverse proxy (Nginx Proxy Manager, SWAG, Caddy, Traefik),
|
||||
il proxy deve passare l'header `Host` originale o `X-Forwarded-Host`, altrimenti ogni
|
||||
salvataggio e ogni comando ricevono 403. I proxy citati lo fanno di fabbrica; un `nginx`
|
||||
scritto a mano vuole `proxy_set_header Host $host;`. Dietro il proxy tutti i client sembrano
|
||||
un solo indirizzo: l'attesa dopo una password sbagliata vale per tutti.
|
||||
|
||||
## Icona
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
<Privileged>false</Privileged>
|
||||
<Support>http://192.168.30.23:3000/Alby96/Encelado/issues</Support>
|
||||
<Project>http://192.168.30.23:3000/Alby96/Encelado</Project>
|
||||
<Overview>Encelado: bot di trading "Correlation Baskets" su eToro (Public API). Motore, ledger e interfaccia web Material 3 in un solo container. Configurazione in /config (encelado.json, strategy.json, chiavi cifrate), dati in /data (ledger, stato, barre, conoscenza, rapporti, log). Le chiavi eToro si mettono nelle variabili ETORO_API_KEY e ETORO_USER_KEY oppure si salvano dall'interfaccia (cifrate con ENCELADO_KEY_PASSPHRASE). Modalita' Live solo con ENCELADO_EXECUTION_MODE=Live, ETORO_ENVIRONMENT=real e la frase CONFERMO LIVE in ENCELADO_CONFIRM_LIVE.</Overview>
|
||||
<Overview>Encelado: bot di trading "Correlation Baskets" su eToro (Public API). Motore, ledger e interfaccia web in un solo container. L'unica cosa da scegliere qui e' la password dell'interfaccia: tutto il resto (conto demo o reale, chiavi eToro dei due conti, Telegram, strategia, valuta, log) si imposta dalla pagina Impostazioni, e il bot applica subito ogni cambio. Le chiavi e il token Telegram restano cifrati in /config con questa password: se la cambi, l'interfaccia chiede quella precedente per riaprirli. La modalita' Live non parte mai da sola: serve AVVIA e la frase CONFERMO LIVE. Configurazione in /config, dati in /data (ledger, stato, barre, conoscenza, rapporti, log).</Overview>
|
||||
<Category>Tools: Productivity:</Category>
|
||||
<WebUI>http://[IP]:[PORT:8080]/</WebUI>
|
||||
<TemplateURL>http://192.168.30.23:3000/Alby96/Encelado/raw/branch/main/deploy/unraid/encelado.xml</TemplateURL>
|
||||
@@ -23,21 +23,7 @@
|
||||
<Requires/>
|
||||
|
||||
<Config Name="Porta web" Target="8080" Default="8080" Mode="tcp" Description="Porta dell'interfaccia web e dell'API (http://IP:porta/)." Type="Port" Display="always" Required="true" Mask="false">8080</Config>
|
||||
<Config Name="Configurazione (/config)" Target="/config" Default="/mnt/user/appdata/encelado/config" Mode="rw" Description="encelado.json, strategy.json, instruments.json e il file cifrato delle chiavi. Seminati al primo avvio dai valori di fabbrica." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/encelado/config</Config>
|
||||
<Config Name="Configurazione (/config)" Target="/config" Default="/mnt/user/appdata/encelado/config" Mode="rw" Description="encelado.json, strategy.json, instruments.json e i segreti cifrati (secrets.enc). Seminati al primo avvio dai valori di fabbrica; si modificano dall'interfaccia." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/encelado/config</Config>
|
||||
<Config Name="Dati (/data)" Target="/data" Default="/mnt/user/appdata/encelado/data" Mode="rw" Description="Ledger (data/ledger), stato (data/state), barre, cache dei feed, conoscenza, rapporti e log. Non cancellare: il ledger e' la memoria del bot." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/encelado/data</Config>
|
||||
|
||||
<Config Name="ETORO_API_KEY" Target="ETORO_API_KEY" Default="" Mode="" Description="Chiave x-api-key di eToro Public API (portale sviluppatori). In alternativa si salvano dall'interfaccia, cifrate con ENCELADO_KEY_PASSPHRASE." Type="Variable" Display="always" Required="false" Mask="true"></Config>
|
||||
<Config Name="ETORO_USER_KEY" Target="ETORO_USER_KEY" Default="" Mode="" Description="Chiave x-user-key di eToro Public API. Demo e reale hanno chiavi diverse." Type="Variable" Display="always" Required="false" Mask="true"></Config>
|
||||
<Config Name="ETORO_ENVIRONMENT" Target="ETORO_ENVIRONMENT" Default="demo" Mode="" Description="Ambiente eToro: demo (denaro virtuale) oppure real (conto reale; serve anche ENCELADO_EXECUTION_MODE=Live e la frase di conferma)." Type="Variable" Display="always" Required="true" Mask="false">demo</Config>
|
||||
<Config Name="ENCELADO_EXECUTION_MODE" Target="ENCELADO_EXECUTION_MODE" Default="Demo" Mode="" Description="Paper (simulatore locale sopra le quotazioni reali), Demo (conto demo eToro, predefinito) o Live (conto reale: richiede run.allowLive=true in encelado.json e la frase in ENCELADO_CONFIRM_LIVE)." Type="Variable" Display="always" Required="true" Mask="false">Demo</Config>
|
||||
<Config Name="ENCELADO_CONFIRM_LIVE" Target="ENCELADO_CONFIRM_LIVE" Default="" Mode="" Description="Solo per la modalita' Live: la frase esatta CONFERMO LIVE. Con qualunque altro valore il bot non parte sul conto reale." Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
|
||||
<Config Name="ENCELADO_WEB_TOKEN" Target="ENCELADO_WEB_TOKEN" Default="" Mode="" Description="Token di accesso all'interfaccia web (una stringa lunga a piacere). SENZA token il server ascolta solo su localhost del container e l'interfaccia non e' raggiungibile dalla rete: mettilo." Type="Variable" Display="always" Required="true" Mask="true"></Config>
|
||||
<Config Name="ENCELADO_WEB_PORT" Target="ENCELADO_WEB_PORT" Default="8080" Mode="" Description="Porta interna di Kestrel. Cambiala solo se cambi anche la mappatura della porta qui sopra." Type="Variable" Display="advanced" Required="false" Mask="false">8080</Config>
|
||||
<Config Name="ENCELADO_DISPLAY_CURRENCY" Target="ENCELADO_DISPLAY_CURRENCY" Default="USD" Mode="" Description="Valuta con cui l'interfaccia mostra gli importi (USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD). Il ledger resta in USD; il tasso viene dalle quotazioni eToro." Type="Variable" Display="always" Required="false" Mask="false">USD</Config>
|
||||
<Config Name="ENCELADO_KEY_PASSPHRASE" Target="ENCELADO_KEY_PASSPHRASE" Default="" Mode="" Description="Passphrase con cui l'interfaccia cifra le chiavi eToro salvate in /config/etoro.keys.enc (AES-256-GCM). Non serve se le chiavi arrivano dalle variabili qui sopra." Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
|
||||
<Config Name="TELEGRAM_BOT_TOKEN" Target="TELEGRAM_BOT_TOKEN" Default="" Mode="" Description="Token del bot Telegram (da @BotFather) per notifiche e comandi. Vuoto = Telegram spento." Type="Variable" Display="always" Required="false" Mask="true"></Config>
|
||||
<Config Name="TELEGRAM_CHAT_ID" Target="TELEGRAM_CHAT_ID" Default="" Mode="" Description="Chat id autorizzata a ricevere le notifiche e a mandare i comandi (/stato, /posizioni, /pausa, /kill CONFERMO...). Ogni altro mittente viene ignorato." Type="Variable" Display="always" Required="false" Mask="false"></Config>
|
||||
<Config Name="TZ" Target="TZ" Default="Europe/Rome" Mode="" Description="Fuso orario degli orari a schermo e nel log (nome IANA). Il ledger resta in UTC." Type="Variable" Display="always" Required="false" Mask="false">Europe/Rome</Config>
|
||||
<Config Name="PUID" Target="PUID" Default="99" Mode="" Description="Utente con cui gira il bot e a cui vengono assegnati /config e /data (99 = nobody su Unraid)." Type="Variable" Display="advanced" Required="false" Mask="false">99</Config>
|
||||
<Config Name="PGID" Target="PGID" Default="100" Mode="" Description="Gruppo del bot (100 = users su Unraid)." Type="Variable" Display="advanced" Required="false" Mask="false">100</Config>
|
||||
<Config Name="Password interfaccia" Target="ENCELADO_PASSWORD" Default="" Mode="" Description="Password di accesso all'interfaccia web (una frase lunga a piacere). Cifra anche le chiavi eToro e il token Telegram salvati dall'interfaccia. Senza password il server ascolta solo su localhost del container e l'interfaccia non e' raggiungibile dalla rete." Type="Variable" Display="always" Required="true" Mask="true"></Config>
|
||||
</Container>
|
||||
@@ -2,14 +2,15 @@
|
||||
# radice, cartelle di configurazione e dati sotto deploy/local (ignorate da git).
|
||||
#
|
||||
# docker compose up --build # costruisce e avvia, log a video (Ctrl+C = stop pulito)
|
||||
# docker compose up -d --build # in background → http://localhost:8080/ (token "sviluppo")
|
||||
# docker compose up -d --build # in background → http://localhost:8080/ (password "sviluppo")
|
||||
# docker compose logs -f encelado # segue il log
|
||||
# docker compose down # ferma (SIGTERM: stop pulito del motore)
|
||||
# Oppure: scripts/run-docker.ps1 (o .sh), che fa le stesse cose e stampa l'indirizzo.
|
||||
#
|
||||
# Le chiavi eToro e il token Telegram NON stanno qui: mettili in un file .env
|
||||
# accanto a questo (ignorato da git) con ETORO_API_KEY=…, ETORO_USER_KEY=…,
|
||||
# TELEGRAM_BOT_TOKEN=…, TELEGRAM_CHAT_ID=…, ENCELADO_WEB_TOKEN=…
|
||||
# L'unica variabile è la password dell'interfaccia (ENCELADO_PASSWORD, di default
|
||||
# "sviluppo", la stessa di F5 e degli script, così i segreti cifrati in deploy/local
|
||||
# restano leggibili in entrambi i modi; una vera in un file .env accanto a questo).
|
||||
# Conto, chiavi eToro, Telegram e tutto il resto si impostano dall'interfaccia.
|
||||
# Per Unraid usa invece il template in deploy/unraid/encelado.xml.
|
||||
|
||||
services:
|
||||
@@ -28,23 +29,5 @@ services:
|
||||
- ./deploy/local/config:/config
|
||||
- ./deploy/local/data:/data
|
||||
environment:
|
||||
TZ: ${TZ:-Europe/Rome}
|
||||
PUID: ${PUID:-1000}
|
||||
PGID: ${PGID:-1000}
|
||||
# demo | real — l'ambiente eToro; real richiede anche ENCELADO_EXECUTION_MODE=Live
|
||||
ETORO_ENVIRONMENT: ${ETORO_ENVIRONMENT:-demo}
|
||||
# Paper | Demo | Live
|
||||
ENCELADO_EXECUTION_MODE: ${ENCELADO_EXECUTION_MODE:-Demo}
|
||||
# Solo per Live: la frase esatta «CONFERMO LIVE», altrimenti il bot non parte
|
||||
ENCELADO_CONFIRM_LIVE: ${ENCELADO_CONFIRM_LIVE:-}
|
||||
ENCELADO_DISPLAY_CURRENCY: ${ENCELADO_DISPLAY_CURRENCY:-USD}
|
||||
# Senza token l'interfaccia è raggiungibile solo da localhost del container:
|
||||
# per usarla dal browser il token serve. "sviluppo" è il default delle prove
|
||||
# in locale; in .env mettine uno vero.
|
||||
ENCELADO_WEB_TOKEN: ${ENCELADO_WEB_TOKEN:-sviluppo}
|
||||
ENCELADO_KEY_PASSPHRASE: ${ENCELADO_KEY_PASSPHRASE:-}
|
||||
ETORO_API_KEY: ${ETORO_API_KEY:-}
|
||||
ETORO_USER_KEY: ${ETORO_USER_KEY:-}
|
||||
TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-}
|
||||
TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-}
|
||||
ENCELADO_PASSWORD: ${ENCELADO_PASSWORD:-sviluppo}
|
||||
stop_grace_period: 45s
|
||||
@@ -0,0 +1,484 @@
|
||||
# API dell'interfaccia web (5.1)
|
||||
|
||||
Aggiornato: 2026-10-01. È il contratto fra il server (`src/Encelado.Server/Web`) e l'interfaccia (`Web/wwwroot`): i nomi dei campi qui sono quelli veri. Chi cambia un campo aggiorna questo file nello stesso commit.
|
||||
|
||||
## Convenzioni
|
||||
|
||||
- JSON scritto a mano con `Utf8JsonWriter` (nessuna serializzazione per riflessione); nomi dei campi in inglese, camelCase.
|
||||
- **Importi in USD**: la conversione nella valuta di visualizzazione la fa solo il browser, con `fxRates` del tick.
|
||||
- **Tempi** in ISO-8601 UTC (`"O"`, es. `2026-09-30T08:15:04.1230000Z`); il browser li mostra nel proprio fuso.
|
||||
- Numeri non finiti (NaN, ∞) → `null`. Un valore sconosciuto è `null`, mai `0`.
|
||||
- Testi per l'operatore (motivazioni, intenti, messaggi) in italiano.
|
||||
- Le risposte dei comandi e delle scritture hanno sempre `{ "ok": bool, "message": string }` più i campi propri.
|
||||
- Autenticazione: se il container ha `ENCELADO_PASSWORD` (alias deprecato `ENCELADO_WEB_TOKEN`) ogni rotta chiede il cookie `encelado_session` o `Authorization: Bearer <password>`; senza sessione le rotte `/api/*` rispondono **401**, le pagine rimandano a `/login`. Libere: `/login`, `/logout`, `/api/health`, `/css/*`, `/img/*`, `/icon.svg`, `/manifest.webmanifest`. Una password errata — dal form o dall'header Bearer — costa al suo indirizzo un'attesa che raddoppia fino a 30 s (vedi [Accesso](#accesso)); il cookie non è una password: valido entra anche durante l'attesa, sbagliato riceve 401 subito.
|
||||
- Rete: il server ascolta su tutte le interfacce solo con una password **e** nel container (o con l'argomento `--listen-all`); fuori dal container (F5, `run-dev`) resta su localhost anche con la password, che lì serve ai segreti della sandbox. Senza password ascolta solo su localhost e non chiede niente.
|
||||
- Richieste da altrove: vedi [Richieste che cambiano qualcosa](#richieste-che-cambiano-qualcosa) (`Content-Type: application/json`, `Origin`, `Sec-Fetch-Site`, Host senza password).
|
||||
- `--sample`: ogni rotta risponde con dati d'esempio realistici e coerenti fra loro (nessuna chiave, nessun mercato), per lavorare sulle pagine e fotografarle. Il server campione lavora in cartelle temporanee (cancellate all'uscita): non legge né scrive la configurazione, i segreti o i dati dell'operatore e non apre il bot Telegram. Le impostazioni sono quelle di fabbrica e ogni scrittura (comandi, impostazioni, segreti) risponde **400** «modalità dimostrativa (--sample)».
|
||||
|
||||
## File statici
|
||||
|
||||
Ogni file incorporato sotto `wwwroot/` è servito al suo percorso (`/css/app.css`, `/js/app.js`, `/js/pages/dashboard.js`, `/img/…`), con il tipo dal suffisso (`.html`, `.css`, `.js` come `text/javascript`, `.svg`, `.webmanifest`, `.png`, `.ico`), `ETag` e `Cache-Control: no-cache` (la richiesta con `If-None-Match` uguale riceve **304**). `/` → `index.html`, `/login` → `login.html`.
|
||||
|
||||
L'interfaccia (docs/UI_GUIDELINES.md): `index.html` carica `/css/tokens.css`, `/css/app.css`, `/css/pages/<pagina>.css`, lo script classico `/js/boot.js` (il tema prima del primo disegno) e il modulo `/js/app.js`, che importa staticamente gli altri moduli di `/js/` e `/js/pages/`. `login.html` non ha script (`/js/*` chiede la sessione) e porta il segnaposto `<!--login-error-->`.
|
||||
|
||||
## Accesso
|
||||
|
||||
- `GET /login` — la pagina.
|
||||
- `POST /login` — form `password` (accettato anche `token`, il nome della 5.0). Corretta: cookie `encelado_session` (HttpOnly, SameSite=Strict, 30 giorni) e **302** su `/`. Il cookie è un HMAC della password e di un segreto del server (32 byte casuali in `/config/session.key`, creato al primo avvio con una password e tenuto fra un riavvio e l'altro), mai la password: senza il segreto non si calcola da una password indovinata. Cambiare la password, o cancellare `session.key`, chiude tutte le sessioni. Errata: **401** con la pagina di login e il messaggio (`<p class="login-error" role="alert">`), messo al posto del segnaposto `<!--login-error-->` se la pagina lo contiene, altrimenti prima di `</form>`, dopo l'attesa qui sotto.
|
||||
- `POST /logout` — cancella il cookie, **302** su `/login`.
|
||||
- `/login` e `/logout` sono form semplici: **403** se l'`Origin` nomina un altro host o porta (vedi sotto); `Sec-Fetch-Site` e `Content-Type` non contano.
|
||||
|
||||
Il prezzo di una password errata (uguale per il form e per `Authorization: Bearer`, contato per indirizzo del client; un client IPv6 per il suo /64): la risposta errata arriva dopo 1 s, poi 2, 4, 8, 16 e al più 30 s per ogni errore di fila. Finché l'attesa non è finita nessuna password di quell'indirizzo viene controllata, nemmeno quella giusta: la richiesta riceve **429** con `Retry-After` (JSON `{ ok: false, message }` sotto `/api/`, la pagina di login con «Troppi tentativi…» altrove). Così i tentativi in parallelo non aiutano. Una password giusta azzera il conto; dieci minuti senza errori lo dimenticano. Il cookie di sessione **non** passa da qui: valido, la richiesta entra subito anche mentre l'indirizzo aspetta (chi tenta password dietro lo stesso NAT, /64 o reverse proxy non tiene fuori una pagina già entrata, né le azzera il conto); sbagliato (una scheda rimasta aperta dopo un cambio di password) o assente, la richiesta non è un tentativo: 401 (o la pagina di login) subito. L'interfaccia, a un 401 o a un 429, torna alla pagina di login e smette di interrogare il server. Gli altri indirizzi non aspettano (dietro un reverse proxy che mostra a Encelado un solo indirizzo, l'attesa per le password vale per tutti).
|
||||
|
||||
## Richieste che cambiano qualcosa
|
||||
|
||||
Controllate prima di guardare la password, su ogni rotta:
|
||||
|
||||
- **Senza password** il server risponde **403** a ogni richiesta (anche GET) il cui header `Host` non è `localhost`, `127.0.0.1` o `[::1]`, con o senza porta: una pagina che fa puntare il proprio nome a 127.0.0.1 (DNS rebinding) manda il suo nome.
|
||||
- Ogni metodo diverso da GET, HEAD e OPTIONS riceve **403** se `Sec-Fetch-Site` è presente e diverso da `same-origin` o `none` (un'altra origine, anche `same-site`), oppure se `Origin` è presente e il suo host:porta è diverso da quello dell'header `Host` (o di `X-Forwarded-Host`, per un reverse proxy che riscrive l'Host; un `Host` senza porta confronta il solo nome). `Origin: null` è sempre un'altra origine. Senza `Origin` né `Sec-Fetch-Site` (uno script con curl) il controllo non scatta. `/login` e `/logout` hanno solo il controllo dell'`Origin`.
|
||||
- Sotto `/api/` ogni POST e DELETE (ogni metodo diverso da GET, HEAD e OPTIONS) deve dire `Content-Type: application/json`, anche senza corpo (`DELETE /api/settings/keys?account=demo`, `POST /api/settings/secrets/reset`…): altrimenti **415**. Un form o una fetch "semplice" di un altro sito non possono mandarlo senza un preflight CORS, che il server non concede mai.
|
||||
|
||||
Le risposte di rifiuto sotto `/api/` sono `{ ok: false, message }`.
|
||||
|
||||
## Il flusso in tempo reale
|
||||
|
||||
### `GET /api/stream` (Server-Sent Events)
|
||||
|
||||
Un tick al secondo, `event: snapshot`, la stessa serializzazione condivisa da tutti i client (niente viene calcolato se nessuno è connesso). Il primo tick arriva subito; il server manda `retry: 3000`. Un client lento riceve solo il tick più recente.
|
||||
|
||||
### `GET /api/snapshot`
|
||||
|
||||
Lo stesso tick, una volta (per il polling senza `EventSource` e per gli screenshot con `?once=1`).
|
||||
|
||||
### Il tick (v2)
|
||||
|
||||
`nowUtc` è sempre il primo campo.
|
||||
|
||||
```ts
|
||||
type Tick = {
|
||||
nowUtc: string; // primo campo
|
||||
v: 2;
|
||||
frame: number; // contatore dei tick del server
|
||||
state: "stopped" | "starting" | "running" | "stopping" | "faulted";
|
||||
error: string; // vuoto se nessun errore
|
||||
account: "demo" | "live"; // modalità: Demo = conto demo, Live = conto reale
|
||||
preset: "Conservative" | "Moderate" | "Aggressive";
|
||||
startedAtUtc: string | null;
|
||||
uptimeSeconds: number;
|
||||
engineTickAgeSeconds: number | null; // da quanto il ciclo di decisione non gira (null a motore fermo)
|
||||
heartbeatSeconds: number; // intervallo del battito del motore in esecuzione (recovery.heartbeatSeconds, 5-600, cambia senza riavvio); 0 se fermo.
|
||||
// L'heartbeat è vecchio oltre 3 × heartbeatSeconds + 15 s (105 s con il default 30): è la soglia di /api/health
|
||||
alarms: {
|
||||
halted: boolean; // kill-switch o equity stop: entrate bloccate fino al reset
|
||||
haltKind: "" | "kill" | "equity";
|
||||
haltReason: string;
|
||||
haltedWithResidue: boolean; // Halted-Residuo: posizioni del bot ancora sul conto
|
||||
residueCount: number;
|
||||
entriesBlockedReason: string; // vuoto se le entrate sono libere
|
||||
entriesBlockedUntilUtc: string | null;
|
||||
paused: boolean; // pausa dell'operatore (/pausa)
|
||||
unreconciled: boolean;
|
||||
unreconciledReason: string;
|
||||
dailyLossHit: boolean; // il calo dell'equity netta da mezzanotte è oltre la soglia adesso, o lo è stato al minimo di un calo del saldo
|
||||
// che lo storico eToro non spiega ancora (entrate sospese finché non si chiarisce); il blocco della giornata è dailyLossLatched
|
||||
recoveryPending: boolean;
|
||||
secretsLocked: boolean; // segreti cifrati con un'altra password
|
||||
liveNeedsConfirmation: boolean; // modalità Live, motore fermo: serve AVVIA con la frase
|
||||
ignoredEnv: string[]; // variabili d'ambiente ignorate (da togliere dal container)
|
||||
};
|
||||
closeForeignOnKill: boolean; // strategy.json → risk.closeForeignOnKill: da qui parte la casella «posizioni esterne» del dialogo del
|
||||
// kill-switch; la scelta del dialogo, sempre esplicita, vale per quel kill-switch (vedi il comando kill)
|
||||
equity: number | null;
|
||||
balance: number | null;
|
||||
availableBalance: number | null;
|
||||
usedMargin: number | null;
|
||||
marginRatio: number | null; // equity / margine usato (null senza margine)
|
||||
peakEquity: number | null; // al netto dei movimenti di cassa
|
||||
drawdownPct: number | null; // 0..1
|
||||
equityStopPct: number; // 0..1, dalla strategia
|
||||
dailyLossPct: number; // 0..1, soglia dalla strategia
|
||||
dailyLossUsedPct: number | null;// 0..1: quanto della soglia giornaliera è consumato
|
||||
dailyLossLatched: boolean; // D-52: la perdita giornaliera è stata raggiunta oggi; niente nuove entrate né aggiunte fino alle 00:00 UTC,
|
||||
// anche se l'equity recupera. Sopravvive al riavvio (stato del conto); false a motore fermo.
|
||||
// Un calo del saldo che lo storico eToro non spiega ancora (forse un prelievo) sospende subito le entrate
|
||||
// (dailyLossHit), anche se intanto l'equity recupera; quando lo storico lo spiega, se era una perdita la
|
||||
// giornata si blocca (giudicata sul minimo toccato nel frattempo), se era un movimento di cassa no.
|
||||
cumulativeCashFlow: number;
|
||||
todayPnl: number | null; // realizzato netto (netProfit − fees) delle posizioni del bot chiuse oggi UTC, dallo storico eToro (+ stime provvisorie)
|
||||
todayPnlPct: number | null; // todayPnl / equity netta di inizio giornata
|
||||
todayPnlProvisional: boolean; // true se contiene stime non ancora confermate dallo storico
|
||||
todayEquityChange: number | null; // equity netta ora − equity netta alle 00:00 UTC (realizzato + variazione dell'aperto, cassa esclusa)
|
||||
dayStartEquity: number | null;
|
||||
todayClosed: { baskets: number; won: number; lost: number; loneLegs: number };
|
||||
openPnl: number | null; // P&L aperto dei basket del bot
|
||||
accountOpenPnl: number | null; // P&L aperto di tutto il conto
|
||||
openBaskets: number;
|
||||
maxBaskets: number;
|
||||
pendingBaskets: number;
|
||||
pendingOrders: number;
|
||||
orphanLegs: number;
|
||||
foreignPositions: number;
|
||||
displayCurrency: string; // USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD
|
||||
theme: "dark" | "light";
|
||||
navExpanded: boolean;
|
||||
statusLines: number; // logging.statusLines (Impostazioni ▸ Log ▸ righe di attività): quante righe tiene la striscia della dashboard,
|
||||
// 20-2000 (il browser ne tiene 2000; un valore più grande scritto a mano nel file vale 2000); cambia subito
|
||||
fxRates: Record<string, { usdPerUnit: number; ageSeconds: number | null }>; // USD compreso (1)
|
||||
baskets: TickBasket[];
|
||||
quotes: Array<{ symbol: string; bid: number | null; ask: number | null; spreadPips: number | null; spreadMedianPips: number | null; ageSeconds: number | null }>;
|
||||
// solo gli strumenti dei basket; le coppie di sola conversione (GBPUSD, USDJPY) sono in /api/market.
|
||||
// bid e ask sono null per uno strumento non ancora quotato (subito dopo AVVIA); spreadPips anche, finché non c'è né una
|
||||
// quotazione né una barra. La pagina mostra «—», mai 0
|
||||
health: {
|
||||
api: "ok" | "degraded" | "error" | "off";
|
||||
apiLatencyMs: number | null; // solo il viaggio HTTP, senza attese del limitatore
|
||||
clockSkewSeconds: number | null;
|
||||
quotaPeakPct: number | null; // 0..1: la classe di quota più usata
|
||||
feeds: "ok" | "stale" | "error" | "off";
|
||||
telegram: "ok" | "queue" | "error" | "off";
|
||||
heartbeatAgeSeconds: number | null;
|
||||
secrets: "open" | "empty" | "locked" | "localKey";
|
||||
sseClients: number;
|
||||
};
|
||||
learning: {
|
||||
mode: "ombra-disabilitato" | "ombra" | "attivo";
|
||||
labelledRows: number; // basket etichettati come li conta il dataset (con le feature d'ingresso): lo stesso numero di dataset.labelledRows
|
||||
// di /api/learning; ricontato dal ledger all'avvio dopo la verifica del realizzato e a ogni ciclo
|
||||
target: number; // 300
|
||||
rollingAuc: number | null;
|
||||
banditPreset: string; // proposta, mai applicata
|
||||
volModel: string; // "EWMA" | "HAR"
|
||||
cycleRunning: boolean;
|
||||
warnings: number;
|
||||
};
|
||||
nextEvent: { timeUtc: string; currency: string; title: string; impact: "High" | "Medium" | "Low" } | null;
|
||||
events: Array<{ seq: number; timeUtc: string; level: "trace" | "debug" | "info" | "warn" | "error"; source: string; message: string }>;
|
||||
// solo le righe di log nuove dall'ultimo tick (≤ 100), già su una riga; il client recupera il pregresso con /api/log
|
||||
eventsSeq: number; // l'ultimo seq emesso finora
|
||||
versions: { positions: number; market: number; learning: number; settings: number; system: number; history: number };
|
||||
// un numero cambia quando la sezione cambia: il client rilegge l'endpoint solo allora
|
||||
};
|
||||
|
||||
type TickBasket = {
|
||||
name: string; // "EURUSD/USDCHF"
|
||||
pairA: string; pairB: string;
|
||||
cross: string; // cross sintetico, "EURCHF"
|
||||
currencies: string[]; // valute coinvolte, es. ["EUR","USD","CHF"] (per le bandiere)
|
||||
state: "Idle" | "Entering" | "PendingA" | "PendingB" | "Open" | "Adding" | "Exiting" | "Closed" | "Error" | "Disabled";
|
||||
enabled: boolean;
|
||||
isOpen: boolean;
|
||||
side: "" | "buy" | "sell"; // verso del cross quando aperto
|
||||
openLegs: number;
|
||||
z: number | null; zIn: number | null; zOut: number | null; zStop: number | null;
|
||||
rho: number | null; rhoShort: number | null; halfLife: number | null;
|
||||
pips: number | null; tpPips: number; pnlUsd: number | null; costPips: number | null;
|
||||
spreadRatioMax: number | null; // spread attuale / mediana 24 h, il peggiore delle due gambe
|
||||
pMl: number | null; mlActive: boolean;
|
||||
barsHeld: number; adds: number; entryZ: number | null;
|
||||
minutesToEvent: number | null;
|
||||
nextEvent: string; // etichetta del motore: "USD 13:33 Core PCE Price Index m/m (fra 37 min)", ora UTC; "—" o
|
||||
// "nessun evento ad alto impatto noto" se non c'è. Il browser la mostra nel proprio fuso.
|
||||
intent: string; // cosa farebbe il bot adesso, o perché non entra (italiano)
|
||||
reasonCodes: string[];
|
||||
};
|
||||
```
|
||||
|
||||
## Sezioni a richiesta
|
||||
|
||||
Ogni sezione ha `asOfUtc`, un `ETag` e risponde **304** a `If-None-Match` uguale. Il client la rilegge quando cambia il numero corrispondente in `versions`, o ogni 30 s mentre la pagina è visibile.
|
||||
|
||||
### `GET /api/positions`
|
||||
|
||||
Le posizioni del conto, classificate a ogni riconciliazione (nessuna chiamata a eToro in più). A motore fermo le legge dallo storico/portafoglio (`source: "history"`) se ci sono le chiavi.
|
||||
|
||||
```ts
|
||||
{ asOfUtc: string; source: "engine" | "history" | "none"; problem: string;
|
||||
totals: { count: number; unrealizedPnl: number; margin: number; fees: number;
|
||||
byOrigin: Record<"basket" | "orfana-bot" | "esterna", { count: number; unrealizedPnl: number; margin: number }> };
|
||||
rows: Array<{ positionId: number; symbol: string; instrumentId: number; side: "long" | "short"; units: number;
|
||||
openRate: number; currentRate: number | null; pips: number | null; openedUtc: string; minutesOpen: number;
|
||||
stopLoss: number | null; takeProfit: number | null; leverage: number; margin: number; exposureUsd: number | null;
|
||||
unrealizedPnl: number | null; fees: number; origin: "basket" | "orfana-bot" | "esterna";
|
||||
basket: string; basketId: string; leg: "A" | "B" | "add" | ""; reason: string }>;
|
||||
pendingOrders: Array<{ clientRef: string; orderId: number; basket: string; basketId: string; leg: string; symbol: string;
|
||||
side: "buy" | "sell"; requestedUnits: number; sentUtc: string; ageSeconds: number; lastStatus: string; checks: number }> }
|
||||
```
|
||||
|
||||
### `GET /api/market`
|
||||
|
||||
```ts
|
||||
{ asOfUtc: string;
|
||||
quotes: Array<{ symbol: string; bid: number | null; ask: number | null; mid: number | null; spreadPips: number | null; spreadMedian24hPips: number | null;
|
||||
spreadRatio: number | null; quoteUtc: string | null; ageSeconds: number | null; realtime: boolean; atrPips: number | null;
|
||||
usedBy: string[]; conversionOnly: boolean }>; // bid, ask, mid e ageSeconds null finché lo strumento non è mai stato quotato
|
||||
fx: Array<{ currency: string; usdPerUnit: number; sourcePair: string; inverted: boolean; timeUtc: string | null; ageSeconds: number | null }>;
|
||||
calendar: { updatedUtc: string | null; state: string;
|
||||
events: Array<{ timeUtc: string; currency: string; title: string; impact: "High" | "Medium" | "Low" | "Holiday";
|
||||
forecast: string; previous: string; actual: string; affectsBaskets: string[]; blackout: boolean }> };
|
||||
sentiment: Array<{ currency: string; net1h: number | null; net4h: number | null; net24h: number | null; hawkish4h: number | null; count24h: number }>;
|
||||
riskOff4h: number | null;
|
||||
news: { updatedUtc: string | null; state: string;
|
||||
items: Array<{ publishedUtc: string; source: string; title: string; link: string; currencies: string[]; net: number; hawkish: number; riskOff: number }> };
|
||||
volatility: Array<{ basket: string; model: "EWMA" | "HAR"; sigmaForecast: number | null; sigmaAverage30d: number | null; ratio: number | null; zInScale: number | null; bars: number }> }
|
||||
```
|
||||
|
||||
Query facoltative: `calendarDays` (default 7), `impact` (default `High,Medium`), `news` (default 50).
|
||||
|
||||
### `GET /api/baskets/detail?name=EURUSD/USDCHF`
|
||||
|
||||
Il nome va nella query (`%2F` nel percorso non verrebbe decodificato).
|
||||
|
||||
```ts
|
||||
{ asOfUtc: string; name: string; pairA: string; pairB: string; cross: string; signB: 1 | -1; enabled: boolean;
|
||||
disabledReason: string; disabledUntilUtc: string | null; state: string; intent: string;
|
||||
lastDecision: { kind: "Skip" | "Enter" | "Add" | "Exit" | "Hold"; reasonCodes: string[]; motivazione: string; atUtc: string } | null;
|
||||
thresholds: { zIn: number; zInEffective: number | null; zOut: number; zStop: number; rhoMin: number; rhoShortMin: number;
|
||||
halfLifeMin: number; halfLifeMax: number; tpPips: number; maxHoldingBars: number; costMultiple: number;
|
||||
spreadMedianMultiple: number; spreadAnomalyMultiple: number; mlMinProbability: number };
|
||||
eval: { z: number | null; dPips: number | null; rhoW: number | null; rhoShort: number | null; halfLife: number | null;
|
||||
atrPipsA: number | null; atrPipsB: number | null; sigmaX: number | null; ewmaVolX: number | null; trendStrength: number | null;
|
||||
priceA: number | null; priceB: number | null; spreadPipsA: number | null; spreadPipsB: number | null;
|
||||
spreadMedianA: number | null; spreadMedianB: number | null; costPips: number | null; breakEvenWinRate: number | null;
|
||||
cost: { passed: boolean; markupPipsA: number; markupPipsB: number; overnightPips: number; reason: string } | null } | null;
|
||||
sizing: { unitsA: number; unitsB: number; notionalUsdA: number; notionalUsdB: number; lossAtStopUsd: number;
|
||||
effectiveLeverage: number; marginUsd: number; bound: string } | null;
|
||||
context: { minutesToNextHigh: number | null; minutesSinceLastHigh: number | null; surpriseLast: number | null;
|
||||
netSentimentDiff1h: number | null; netSentimentDiff4h: number | null; netSentimentDiff24h: number | null;
|
||||
hawkishDiff: number | null; riskOff: number | null; newsCount: number; nextEventLabel: string };
|
||||
ml: { pMl: number | null; active: boolean; features: Array<{ name: string; label: string; value: number | null }> };
|
||||
vol: { sigmaForecast: number | null; sigmaAverage30d: number | null; model: string };
|
||||
position: null | { basketId: string; buyCross: boolean; openedUtc: string; minutesOpen: number; barsHeld: number; adds: number;
|
||||
entryZ: number; lastAddZ: number | null; entryCostPips: number; tpPips: number; zStop: number; maxAdds: number;
|
||||
pipsOpen: number | null; pnlOpenUsd: number | null; accruedFeesUsd: number; maxLossUsd: number;
|
||||
stopDistanceUsd: number | null; zStopDistance: number | null; barsToTimeStop: number | null;
|
||||
barsWithBrokenCorrelation: number; barsWithSpreadAnomaly: number; equityAtEntry: number; entryMotivazione: string;
|
||||
legs: Array<{ leg: "A" | "B"; symbol: string; side: "buy" | "sell"; units: number; totalUnits: number; entryPrice: number;
|
||||
bid: number | null; ask: number | null; pips: number | null; pnlUsd: number | null; entryFeesUsd: number;
|
||||
nativeStopLoss: number | null; positionIds: number[];
|
||||
venue: { unrealizedPnl: number | null; fees: number; currentRate: number | null; margin: number; leverage: number } | null }> };
|
||||
pending: null | { leg: "A" | "B"; decidedUtc: string; ageSeconds: number; unitsA: number; unitsB: number; entryZ: number };
|
||||
recent: Array<{ atUtc: string; evento: string; z: number | null; motivazione: string }> } // ultime 20 decisioni di chiusura barra, dalla più recente
|
||||
```
|
||||
|
||||
### `GET /api/system`
|
||||
|
||||
Tutto ciò che non serve in dashboard: stato del motore, collegamento eToro, quote, feed, Telegram, processo, disco, log, informazioni.
|
||||
|
||||
```ts
|
||||
{ asOfUtc: string;
|
||||
engine: { state: string; account: "demo" | "live"; runId: string; strategyHash: string; preset: string;
|
||||
startedUtc: string | null; uptimeSeconds: number; lastTickUtc: string | null; tickAgeSeconds: number | null;
|
||||
heartbeatUtc: string | null; heartbeatAgeSeconds: number | null;
|
||||
heartbeatSeconds: number; heartbeatStaleSeconds: number; // intervallo del battito e soglia di /api/health (3 × intervallo + 15 s); 0 a motore fermo
|
||||
recoveryPending: boolean; recoveryCause: string;
|
||||
entriesBlockedReason: string; entriesBlockedUntilUtc: string | null; paused: boolean; autostart: boolean;
|
||||
orphanPolicy: "Close" | "Report"; instanceLock: string };
|
||||
api: { endpoint: string; account: "demo" | "live"; state: string; latencyMs: number | null; latencyAvg1mMs: number | null;
|
||||
clockSkewSeconds: number | null; clockSkewMaxSeconds: number; consecutiveErrors: number;
|
||||
lastError: { utc: string; message: string } | null;
|
||||
quotas: Array<{ name: string; used: number; limit: number; windowSeconds: number; pausedUntilUtc: string | null; count429: number }> };
|
||||
feeds: Array<{ name: string; kind: "calendar" | "rss"; currency: string; host: string; lastRequestUtc: string | null;
|
||||
lastSuccessUtc: string | null; failures: number; backoffUntilUtc: string | null; robotsAllowed: boolean | null; lastError: string }>;
|
||||
telegram: { configured: boolean; enabled: boolean; commands: boolean; hourlyStatus: boolean; eventAlerts: boolean;
|
||||
dailySummaryUtcHour: number; chatId: string; queued: number; sent: number; failed: number;
|
||||
lastDeliveredUtc: string | null; lastError: string };
|
||||
secrets: { state: "open" | "empty" | "locked" | "localKey"; etoro: { demo: SecretInfo; live: SecretInfo }; telegram: SecretInfo;
|
||||
passwordSource: "ENCELADO_PASSWORD" | "ENCELADO_WEB_TOKEN" | "none"; ignoredEnv: string[]; importNote: string; problem: string };
|
||||
process: { version: string; informationalVersion: string; commit: string; buildDate: string; dotnet: string; os: string;
|
||||
container: boolean; pid: number; serverUptimeSeconds: number; workingSetBytes: number; gcHeapBytes: number;
|
||||
gen0: number; gen1: number; gen2: number; gcPauseTimePct: number | null; threadPoolThreads: number; timeZone: string };
|
||||
disk: { configPath: string; strategyPath: string; dataPath: string; knowledgePath: string; reportsPath: string; logFile: string;
|
||||
freeBytes: number | null; totalBytes: number | null; writable: boolean; checkedUtc: string; logBytes: number | null };
|
||||
log: { enqueued: number; dropped: number; bufferLines: number; bufferCapacity: number; level: string };
|
||||
web: { sseClients: number; framesSent: number; lastFrameBytes: number };
|
||||
about: { name: "Encelado"; author: "Alberto Balbo"; version: string; buildDate: string; commit: string; license: string; docs: string } }
|
||||
|
||||
type SecretInfo = { present: boolean; masked: string; savedUtc: string | null };
|
||||
```
|
||||
|
||||
### `GET /api/learning`
|
||||
|
||||
Il rapporto sull'apprendimento. La parte viva la pubblica il motore (immutabile); a motore fermo e per i file di `knowledge/` la legge dal disco in sola lettura. Query: `features=all` aggiunge il vettore completo per basket. L'`ETag` è la versione della sezione (`versions.learning`) con l'impronta dei file letti — modelli, `knowledge/`, `baskets.csv`, i file delle decisioni e `strategy.json`, da cui un motore fermo prende interruttori, `pMin` e basket: anche una modifica a mano del file cambia l'`ETag` (entro 2 s) —: con `If-None-Match` uguale la risposta è **304** senza costruire niente. Ogni salvataggio di un campo `strategy:` dalle Impostazioni fa avanzare `versions.learning`, così la pagina rilegge subito. `generatedUtc` è l'ora in cui il motore ha pubblicato il rapporto (o quella della lettura dal disco).
|
||||
|
||||
I contributi di un basket (`topContributions`, `features`) spiegano sempre la `pMl` mostrata accanto: vengono dal modello che l'ha data, nel momento in cui l'ha data, e la somma dei `contribution` di `features` più `intercept` è il logit di `pMl`. Il motore li prende insieme alla p a ogni chiusura di barra a basket piatto e li conserva con l'ingresso, anche in `learning_state.json` (così sopravvivono a un riavvio). Una p che nessuna spiegazione accompagna è mostrata senza contributi (`topContributions` vuoto, `features` vuoto con `features=all`, `intercept` `null`): per esempio la p all'ingresso di un basket aperto prima della 5.1, quando il modello nel frattempo è cambiato, o la p del campione MLP. Senza `pMl` (il modello non ha ancora visto un basket) non ci sono contributi.
|
||||
|
||||
A motore fermo:
|
||||
- per un basket in posizione all'ultima riga di valutazione, `pMl` è quella dell'ingresso con i contributi salvati con l'ingresso (`pMlKind` «all'ingresso», `pMlUtc` l'ora dell'ingresso);
|
||||
- per un basket senza posizione, `pMl` è quella dell'ultima riga di valutazione del ledger se il modello salvato la ridà per i valori di quella riga (`pMlKind` «ultima barra»); altrimenti — il modello ha imparato dopo quella barra, o il motore aveva dato al modello un vettore diverso da quello che la riga registra (il vettore valutato alla chiusura di barra non ha ancora il costo dell'ingresso, la riga sì) — è quella che il modello salvato dà ai valori della riga (`pMlKind` «ricalcolata con il modello di oggi», `pMlUtc` l'ora della riga);
|
||||
- `vol` porta solo σ prevista, σ media, rapporto e scala di `z_in` dell'ultima riga (`bars` 0, `activeModel` vuoto, `context` −1), oppure `null`;
|
||||
- un file dei modelli che non si riesce a leggere (modificato a mano, schema diverso) lascia l'ultima lettura buona di quella parte, e un avviso in `warnings` lo dice («… non leggibile (…): mostro l'ultima lettura buona»); se non c'è mai stata una lettura buona l'avviso dice che sono mostrati i valori iniziali. Un file assente vale i valori iniziali, senza avviso.
|
||||
|
||||
`dataset` è ricalcolato quando cambia `baskets.csv`, quando compare un file delle decisioni, quando il ledger riceve una correzione `pnl_realizzato` o la marcatura `feature_inaffidabile` di `lastNOutcomes` (lette in modo incrementale), e comunque al più ogni ora.
|
||||
|
||||
```ts
|
||||
{ schema: 1; generatedUtc: string; source: "engine" | "disk"; engineState: string;
|
||||
status: { mode: "ombra-disabilitato" | "ombra" | "attivo"; enabled: boolean; weeklyCycle: boolean; challengerEnabled: boolean;
|
||||
activeFlag: boolean; gateEffective: boolean; champion: string; modelVersion: number; seen: number;
|
||||
pMin: number; deactivationAuc: number; lastReport: string; reason: string; trackedEntries: number };
|
||||
dataset: null | { computedUtc: string; datasetHash: string; closedRows: number; labelledRows: number; withoutEntryRow: number;
|
||||
entryRowsWithoutFeatures: number; loneLegRows: number; correctedRows: number; unverifiedRows: number;
|
||||
wins: number; losses: number; winRate: number | null; pnlNetUsd: number; meanPnlUsd: number | null;
|
||||
medianPnlUsd: number | null; p5PnlUsd: number | null; firstOpenedUtc: string | null; lastClosedUtc: string | null;
|
||||
demoClosed: number; activationTarget: number; activationProgress: number;
|
||||
byMode: Array<{ key: string; count: number }>;
|
||||
byBasket: GroupStats[]; byPreset: GroupStats[]; byExitReason: GroupStats[];
|
||||
labelsSuspect: boolean; labelsSuspectReason: string };
|
||||
activation: { passesWalkForward: boolean; passesAdr0006: boolean; operatorEnabled: boolean; motivazione: string;
|
||||
items: Array<{ key: string; label: string; current: string; required: string; ok: boolean | null; source: string }> };
|
||||
logistic: { inputs: number; seen: number; learningRate0: number; currentLearningRate: number; l2: number; bias: number;
|
||||
weightNorm: number; standardizerRows: number; standardizerHalfLifeRows: number;
|
||||
weights: Array<{ index: number; name: string; label: string; weight: number; mean: number; stdDev: number }> }; // per |peso| decrescente
|
||||
challenger: null | { hidden: number; seed: number; seen: number; outputBias: number; w1Norm: number; w2Norm: number;
|
||||
silentUnits: number; standardizerRows: number; challengerWins: boolean };
|
||||
lastCycle: null | { version: number; utc: string; durationMs: number; trigger: "settimanale" | "manuale" | "offline"; rows: number;
|
||||
datasetHash: string; trainedOnUntilUtc: string | null; logistic: ModelEvaluation; mlp: ModelEvaluation | null; challengerWins: boolean };
|
||||
rolling: { count: number; pAt: "entry" | "close"; auc100: number | null; auc200: number | null; auc100Low: number | null; auc100High: number | null;
|
||||
brier100: number | null; logLoss100: number | null; hitRate100: number | null; meanP100: number | null; lastOutcomes10: number | null;
|
||||
recentP: number[]; recentLabel: number[]; aucHistory: Array<{ utc: string; auc100: number }>; calibration: CalibrationBin[] };
|
||||
baskets: Array<{ basket: string; cross: string; enabled: boolean; state: string; pMl: number | null; pMlUtc: string | null;
|
||||
pMlKind: "ultima barra" | "all'ingresso" | "ricalcolata con il modello di oggi" | "";
|
||||
intercept: number | null; // intercetta del modello che ha dato pMl: Σ features[].contribution + intercept = logit(pMl); null senza contributi
|
||||
wouldBeFiltered: boolean;
|
||||
topContributions: Array<{ index: number; name: string; label: string; value: number | null; z: number | null; contribution: number | null }>;
|
||||
features: Array<{ index: number; name: string; label: string; value: number | null; z: number | null; contribution: number | null }> | null;
|
||||
vol: null | { bars: number; activeModel: string; ewmaSigma: number | null; harSigma: number | null; forecastSigma: number | null;
|
||||
average30dSigma: number | null; volRatio: number | null; zInScale: number | null; rmseEwma: number | null;
|
||||
rmseHar: number | null; scored: number; pending: number; lastHarFitUtc: string | null; context: number; contextLabel: string } }>;
|
||||
bandit: { contexts: number; explorationCap: number; choices: number; explorations: number; explorationShare: number | null;
|
||||
currentPreset: string; applied: false; rewardsSuspect: boolean;
|
||||
arms: Array<{ context: number; contextLabel: string; preset: string; alpha: number; beta: number; successes: number; failures: number;
|
||||
n: number; mean: number; low95: number; high95: number; bestInContext: boolean }>;
|
||||
// bestInContext: la media a posteriori più alta del contesto, solo per un braccio con almeno un esito (n > 0):
|
||||
// un bandit nuovo non ha bracci migliori, e nemmeno un contesto i cui bracci provati non fanno meglio del prior
|
||||
// (a pari media vince il primo braccio nell'ordine Conservative, Moderate, Aggressive)
|
||||
lastProposal: null | { utc: string; context: number; preset: string; explored: boolean; means: number[]; text: string } };
|
||||
volatility: null | { historyCount: number; tercileLow: number | null; tercileHigh: number | null };
|
||||
knowledge: { calibration: Array<{ dimension: string; bucket: string; count: number; winRate: number | null; meanPnl: number | null; totalPnl: number | null; motivazione: string }>;
|
||||
proposals: Array<{ utc: string; origin: string; parameter: string; currentValue: string; proposedValue: string; evidence: string; state: string; motivazione: string; basedOnSuspectData: boolean }>;
|
||||
registry: Array<{ version: string; utc: string; type: string; nTrain: number; aucWf: number | null; brier: number | null; logLoss: number | null; state: string; motivazione: string }>;
|
||||
insights: null | { fileName: string; modifiedUtc: string; markdown: string; truncated: boolean };
|
||||
modelFiles: Array<{ name: string; bytes: number; modifiedUtc: string; kind: string; version: number | null; rows: number | null }>;
|
||||
files: Array<{ name: string; bytes: number; modifiedUtc: string }> };
|
||||
schedule: { lastCycleUtc: string | null; nextDueUtc: string | null; runsInBot: boolean; due: boolean; running: boolean;
|
||||
runningSinceUtc: string | null; runningPhase: string; lastDurationMs: number | null; lastError: string; lastTrigger: string };
|
||||
warnings: string[] }
|
||||
|
||||
type GroupStats = { key: string; count: number; winRate: number | null; pnlNetUsd: number; meanPnlUsd: number | null };
|
||||
type CalibrationBin = { lower: number; upper: number; count: number; meanPredicted: number | null; observedRate: number | null };
|
||||
type ModelEvaluation = { model: string; rows: number; burnIn: number; auc: number | null; aucLow: number | null; aucHigh: number | null;
|
||||
brier: number | null; logLoss: number | null; calibration: CalibrationBin[]; pnlAllUsd: number; pnlFilteredUsd: number;
|
||||
filteredCount: number; sharpeAll: number | null; sharpeFiltered: number | null; dsrFiltered: number | null;
|
||||
passesActivation: boolean; motivazione: string };
|
||||
```
|
||||
|
||||
### `GET /api/log?level=&q=&limit=&after=`
|
||||
|
||||
`level`: `tutti` (default), `info`, `warn`, `error` (minimo). `q`: testo (nel messaggio o nella sorgente). `limit`: default 500, massimo 5000. `after`: solo le righe con `seq` maggiore.
|
||||
|
||||
```ts
|
||||
{ lastSeq: number; file: string;
|
||||
rows: Array<{ seq: number; timeUtc: string; time: string; level: string; source: string; message: string }> }
|
||||
// message è sempre su una riga: gli a capo diventano " ⏎ "
|
||||
```
|
||||
|
||||
### Storico (invariato dalla 5.0)
|
||||
|
||||
`GET /api/history/orders | positions | periods` con i filtri `from`, `to`, `basket`, `symbol`, `outcome`, `origin` e `format=csv`. Forma delle righe come in `src/Encelado.Server/Web/WebHost.cs` (la pagina Storico della 5.0).
|
||||
|
||||
## Comandi
|
||||
|
||||
`POST /api/commands/{nome}` con corpo JSON facoltativo, sempre con `Content-Type: application/json` (anche senza corpo; 415 altrimenti). Risposta `{ ok, message, needsPhrase, code?, … }`: `needsPhrase` è `true` (HTTP **409**) quando serve la frase `CONFERMO LIVE`; `code` (se presente) è `needsPhrase`, `restart`, `refused` o `timeout`. Anche `refused` risponde **409**: lo stato rifiuta il comando adesso (un ciclo di apprendimento già in corso, AVVIA durante la manutenzione a motore fermo, il motore che si avvia o si ferma, FERMA durante un kill-switch) e il messaggio dice perché. Un comando che il motore non ha eseguito perché si è fermato prima di prenderlo, o a metà, risponde subito `refused` con «comando interrotto: il motore si è fermato» (mai un'attesa di 120 s). `timeout` risponde **504**: il motore, occupato, non ha risposto entro 120 s; il comando resta in coda e l'esito va nel log (per un kill-switch, una chiusura o la chiusura dei residui il messaggio dice che il motore lo porta a termine e che FERMA e i riavvii aspettano). Nessun comando risponde 500 per un'attesa scaduta.
|
||||
|
||||
Il ciclo di vita del motore è serializzato: AVVIA, FERMA, i riavvii automatici delle impostazioni e il ciclo di apprendimento a motore fermo passano uno alla volta. FERMA durante un avvio aspetta il motore in costruzione e lo ferma; AVVIA subito dopo FERMA aspetta che il motore precedente abbia lasciato la cartella dati (lo stato resta `stopping` fino ad allora). Un kill-switch, una chiusura (`close`), la chiusura dei residui o una chiusura della bonifica in coda o in corso non vengono mai interrotti da FERMA o da un riavvio automatico (409 `refused`), anche quando chi li ha chiesti ha smesso di aspettare la risposta (scheda chiusa o ricaricata, risposta 504 dopo 120 s, poller Telegram fermato durante `/kill`): contano finché il motore non li ha conclusi, o finché la sua esecuzione non finisce senza prenderli. Solo l'arresto del processo (SIGTERM) li interrompe, dopo 30 s, e un kill-switch interrotto lascia il residuo registrato (Halted-Residuo).
|
||||
|
||||
| Nome | Corpo | Effetto |
|
||||
|---|---|---|
|
||||
| `start` | `{ confirm?: string }` | Avvia il motore. In modalità Live serve `confirm = "CONFERMO LIVE"` (409 `needsPhrase` altrimenti). 409 `refused` mentre gira un ciclo di apprendimento a motore fermo. |
|
||||
| `stop` | — | Ferma il motore; i basket restano sul conto salvo `run.closeOnShutdown`, con cui il motore stesso, sul suo thread di decisione, blocca le nuove entrate e chiude basket, gambe in attesa e orfane (al più 30 s) prima di fermarsi. 409 `refused` mentre è in corso un kill-switch, una chiusura o la chiusura dei residui. |
|
||||
| `close` | `{ argument: "EURUSD/USDCHF" }` | Chiude il basket. |
|
||||
| `kill` | `{ foreign?: boolean }` | Kill-switch. `foreign` esplicito decide per le posizioni esterne e vince sull'impostazione `risk.closeForeignOnKill`: `true` le chiude, `false` le lascia (il dialogo manda sempre il valore della sua casella, che parte da `closeForeignOnKill` del tick). Senza il campo, o `null`, vale l'impostazione, come per Telegram `/kill` e il file STOP; la console chiede solo se ci sono posizioni esterne e propone l'impostazione come risposta di partenza. Un altro valore risponde 400. Risposta con `positions[]` residue. |
|
||||
| `reset` | `{ reason: string }` | Ripristino in cinque passi; risposta con `steps[]`. |
|
||||
| `residue` | `{ argument?: "all" \| "<positionId>" }` | Richiude i residui del kill-switch. Le gambe di un basket rimasto aperto diventano una riga sola di `baskets.csv`, come basket, quando tutte sono chiuse; una posizione già registrata (chiusa nel frattempo dall'uscita del basket o da eToro) non riceve una seconda riga. Un residuo che il conto non mostra più esce dall'elenco alla riconciliazione successiva. |
|
||||
| `pause`, `resume` | — | Pausa/ripresa delle entrate. |
|
||||
| `bonifica` | `{ argument: "list" \| "close:<positionId>" }` | Elenco o chiusura delle orfane; `positions[]`. |
|
||||
| `learn` | — | Ciclo di apprendimento in background. Motore acceso: lo avvia il motore e la risposta è immediata (avanzamento in `schedule.running` / `runningPhase` di `/api/learning` e in `learning.cycleRunning` del tick). Motore fermo o in errore: manutenzione che prende il lock di istanza della cartella dati; `start` risponde 409 `refused` finché dura. 409 `refused` con un ciclo già in corso, con il motore che si avvia (finché il ciclo di decisione non è partito: verifica, riscaldamento, riconciliazione) o si ferma, o con il lock tenuto da un altro processo. |
|
||||
|
||||
Le righe di `positions[]` (`kill`, `residue`, `bonifica`) hanno la forma della 5.0: `{ positionId: number; symbol: string; isBuy: boolean; units: number | null; openedUtc: string; unrealizedPnl: number | null; origin: "basket" | "orfana-bot" | "esterna"; basket: string; reason: string }`.
|
||||
|
||||
In `--sample` ogni comando risponde `{ ok: false, message: "modalità dimostrativa (--sample): …" }` con HTTP **400**: niente viene eseguito.
|
||||
|
||||
Il comando `preset` non esiste più: il preset si cambia in Impostazioni.
|
||||
|
||||
## Impostazioni
|
||||
|
||||
### `GET /api/settings`
|
||||
|
||||
```ts
|
||||
{ configPath: string; strategyPath: string;
|
||||
version: number; // cambia a ogni salvataggio (impostazioni o segreti)
|
||||
engine: { state: string; account: "demo" | "live"; running: boolean };
|
||||
groups: Array<{ key: string; title: string; description: string; target: "config" | "strategy"; advanced: boolean;
|
||||
// key: "conto" | "esecuzione" | "strategia" | "avanzate" | "telegram" | "interfaccia" | "log"
|
||||
fields: Array<{ path: string; // "run.pollSeconds" oppure "strategy:preset"
|
||||
label: string; kind: "text" | "number" | "integer" | "choice" | "bool" | "list";
|
||||
value: string; // sempre stringa; bool = "true"/"false"; list = valori separati da virgola
|
||||
options: string[]; // per choice
|
||||
suffix: string; tooltip: string; readOnly: boolean; error: string;
|
||||
scope: "immediate" | "engine" | "restart"; // quando ha effetto
|
||||
min: number | null; max: number | null;
|
||||
allowEmpty: boolean }> }>; // vuoto ammesso: per un numero significa "il valore del preset" (la chiave sparisce dal file)
|
||||
secrets: { state: "open" | "empty" | "locked" | "localKey"; etoro: { demo: SecretInfo; live: SecretInfo }; telegram: SecretInfo;
|
||||
passwordSource: string; ignoredEnv: string[];
|
||||
importNote: string; // cosa ha fatto l'importazione una tantum dalla 5.0 (vuoto se niente)
|
||||
problem: string } } // perché i segreti sono bloccati (vuoto altrimenti)
|
||||
```
|
||||
|
||||
L'input è tollerante: un numero può avere la virgola decimale (`0,65`), un booleano può essere `sì`/`no`; il valore restituito è sempre normalizzato (`0.65`, `true`). Le stringhe arrivano già in italiano.
|
||||
|
||||
In `--sample` la risposta è un dato d'esempio: i valori di fabbrica di `encelado.json` e `strategy.json` (nessun file viene letto), il motore e i segreti del campione (gli stessi di `/api/system`); `configPath` e `strategyPath` dicono «campione (--sample): valori di fabbrica» e «niente viene salvato». Ogni scrittura di questa sezione e di [Segreti](#segreti) risponde **400** `{ ok: false, message: "modalità dimostrativa (--sample): le impostazioni e i segreti non vengono salvati", … }` senza leggere il corpo né chiamare eToro o Telegram.
|
||||
|
||||
### `POST /api/settings`
|
||||
|
||||
Corpo `{ "edits": { "<path>": "<valore>", … }, "confirm"?: "CONFERMO LIVE" }` (accettato anche l'oggetto piatto `{ "<path>": "<valore>" }` della 5.0).
|
||||
|
||||
Risposta:
|
||||
|
||||
```ts
|
||||
{ ok: boolean; message: string;
|
||||
results: Array<{ path: string; applied: "immediate" | "engine" | "restart" | "stored" | "error"; message: string }>;
|
||||
restart: "none" | "done" | "needsPhrase" | "refused";
|
||||
needsPhrase: boolean; // = restart === "needsPhrase"
|
||||
errors: Record<string, string>; // path → errore di validazione ("*" = la combinazione dei valori)
|
||||
version: number }
|
||||
```
|
||||
|
||||
Con `restart = "needsPhrase"` (HTTP 409) niente è stato scritto: il client chiede la frase e ripete con `confirm`. Con `restart = "refused"` (HTTP 409) niente è stato scritto, e `message` dice perché: mancano le chiavi del conto scelto a motore acceso, oppure il cambio riavvierebbe il motore mentre è in corso un kill-switch, una chiusura o la chiusura dei residui, oppure — per il cambio di conto (Demo ↔ Live) o delle coppie dei basket — sul conto in uso c'è ancora qualcosa in sospeso: basket aperti o in attesa di una gamba, ingressi, aggiunte o uscite in corso, basket in errore con una gamba sul conto, ordini senza esito, gambe orfane del bot o residui del kill-switch, chiusure in attesa dello storico eToro (al più 30 minuti). Il messaggio elenca solo ciò che c'è e dice cosa fare. Lo stesso cambio è rifiutato mentre il motore si avvia (finché il ciclo di decisione non è partito non ha letto il suo stato), mentre si ferma, o se il motore, occupato, non risponde al controllo entro 30 s. Valori non validi: HTTP 400 con `errors`.
|
||||
|
||||
Il controllo del cambio di conto (decisione C8) a motore acceso lo fa il motore stesso, sul suo thread di decisione, dopo aver bloccato le nuove entrate e le aggiunte e dopo una riconciliazione con il conto: mai la vista pubblicata, dove un basket a metà ingresso sembra piatto, né l'ultima riconciliazione, che può avere fino a 20 s (una gamba del bot che nessuno slot tiene — la gamba A rimasta sul conto quando la sua richiusura è stata rifiutata — diventa così un'orfana e conta). Se le posizioni del conto non si leggono, il cambio è rifiutato («le posizioni del conto non lette da eToro»). Se il conto è libero le entrate restano bloccate fino al riavvio (`alarms.entriesBlockedReason` lo dice nel frattempo); se il cambio poi non avviene, il blocco viene tolto. A motore fermo decide il file di stato del conto in uso. Dopo l'arresto, prima di avviare l'altro conto, il file lasciato dal motore fermato viene giudicato di nuovo: se il conto non è piatto — o se nel frattempo è partito un kill-switch, una chiusura o la chiusura dei residui, o FERMA ha lasciato il conto non piatto — `encelado.json` e `strategy.json` tornano byte per byte come prima del salvataggio e la risposta è 409 `refused` con il motivo; il motore resta fermo (o acceso sul conto di prima, se non era stato fermato). Ogni conto ha il suo stato (basket, blocchi, residui, pausa, picco, chiusure in attesa del P&L), che il cambio non tocca: tornando sull'altro conto lo si ritrova com'era.
|
||||
|
||||
Il riavvio automatico riavvia solo un motore che è ancora acceso quando tocca a lui: se nel frattempo è arrivato FERMA, il motore resta fermo e i valori salvati valgono al prossimo avvio (`applied = "stored"`, `restart = "none"`). Se i file sono stati scritti ma il riavvio non è riuscito (raro: un kill-switch partito fra il controllo e il riavvio, o il motore fermato che non riparte) la risposta è HTTP 400 con `ok: false` e un messaggio che dice che i valori sono salvati e cosa fare («salvato, ma il motore non è stato riavviato: …», «il motore si è fermato ma non è ripartito: …»).
|
||||
|
||||
### Segreti
|
||||
|
||||
| Rotta | Corpo | Effetto |
|
||||
|---|---|---|
|
||||
| `POST /api/settings/keys` | `{ account: "demo" \| "live", apiKey, userKey }` | Verifica le chiavi su quel conto (profilo e saldo) e le salva cifrate. Se è il conto attivo e il motore gira, lo riavvia (Live: serve `confirm`). |
|
||||
| `DELETE /api/settings/keys?account=demo` | — | Rimuove le chiavi di quel conto (a motore fermo, o del conto non attivo). |
|
||||
| `POST /api/settings/telegram-token` | `{ token }` | Verifica con `getMe` e salva cifrato; riconfigura Telegram subito. |
|
||||
| `DELETE /api/settings/telegram-token` | — | Rimuove il token; Telegram si spegne. |
|
||||
| `POST /api/settings/telegram-test` | — | Manda un messaggio di prova alla chat configurata. |
|
||||
| `POST /api/settings/secrets/unlock` | `{ previous }` | Decifra con la password precedente e ricifra con quella attuale. |
|
||||
| `POST /api/settings/secrets/reset` | — | Ricomincia con un deposito vuoto (il vecchio file resta come `.bak`). |
|
||||
| `POST /api/settings/restore` | — | Valori di fabbrica di `encelado.json` (a motore fermo; backup con la data). |
|
||||
|
||||
Ogni rotta dei segreti risponde `{ ok, message, restart, needsPhrase, detail, version }`: `detail` è ciò che la verifica ha trovato (utente ed equity del conto, nome del bot Telegram) o il percorso del backup. Chiavi rifiutate da eToro o token rifiutato da Telegram: HTTP 400, niente salvato. Deposito bloccato o chiavi del conto in uso a motore acceso: HTTP 409. Nuove chiavi del conto in uso mentre è in corso un kill-switch, una chiusura o la chiusura dei residui: HTTP 409 `restart = "refused"`, niente salvato. Lo stato del motore e il conto in uso si rileggono dopo la verifica (che dura fino a 25 s): se nel frattempo è arrivato FERMA, o il conto è cambiato e le chiavi non sono più del conto del motore, vengono salvate senza riavviare niente; se il motore da riavviare ora è in Live e il salvataggio non portava la frase, vengono salvate e il motore non viene riavviato (il messaggio dice di premere FERMA e poi AVVIA con `CONFERMO LIVE`). Chiavi salvate ma motore che non riparte dopo il riavvio: HTTP 500 con `ok: false`, `restart = "done"` e il motivo (le chiavi restano salvate); un errore del disco nel «Ricomincia» del deposito: HTTP 500.
|
||||
|
||||
## Salute
|
||||
|
||||
`GET /api/health` (libera, per il `HEALTHCHECK` del container):
|
||||
|
||||
```ts
|
||||
{ ok: boolean; state: string; apiState: string; heartbeatAgeSeconds: number | null; heartbeatSeconds: number; diskWritable: boolean; uptimeSeconds: number }
|
||||
```
|
||||
|
||||
`ok` è falso se il disco dei dati non è scrivibile o se, a motore acceso, l'heartbeat è più vecchio di 3 × `heartbeatSeconds` + 15 s (105 s con il default di 30 s; `heartbeatSeconds` è l'intervallo che il motore sta usando, 0 a motore fermo); prima del primo heartbeat, se l'avvio risale a più di dieci minuti. `apiState` usa le parole di `health.api` del tick (`ok`, `degraded`, `error`, `off`). La prova di scrittura del disco si ripete al più una volta al minuto; nessuno snapshot viene costruito.
|
||||
@@ -1,75 +1,106 @@
|
||||
# Architettura di Encelado
|
||||
|
||||
Aggiornato: 2026-09-23 (5.0: Engine + Server, interfaccia web, container). La storia della ricognizione del 2026-09-16 (l'albero che non compilava, i motori Binance/cTrader, SQLite) è nella versione precedente di questo file nella storia git e in ADR-0004.
|
||||
Aggiornato: 2026-10-01 (5.1: viste pubblicate e tick condiviso, impostazioni applicate a caldo, segreti cifrati con la password, stato per conto, realizzato dallo storico, ciclo di apprendimento in background, interfaccia in stile Mimante). La storia della ricognizione del 2026-09-16 (l'albero che non compilava, i motori Binance/cTrader, SQLite) è nella versione della 4.0 di questo file nella storia git e in ADR-0004.
|
||||
|
||||
## 1. Progetti
|
||||
|
||||
```
|
||||
Encelado.slnx
|
||||
├── src/Encelado.Core libreria portabile (net10.0), zero NuGet, AOT/trim-compatibile, zero I/O
|
||||
│ ├── Broker/ IBroker, modelli (Instrument, QuoteSnapshot, AccountSnapshot, BrokerPosition, ClosedTrade, OrderRequest, OrderOutcome), PaperBroker, RateLimiter
|
||||
│ ├── Baskets/ SyntheticCross, PipMath, BasketMath, SymbolSeries, BasketDecider, CostGate, VolParitySizing, BasketExecutor, BasketPosition (con PendingA/PendingB),
|
||||
│ │ PendingEntry, BasketStrategyConfig (strategy.json, preset, risk, recovery, learning), OrderTracker (ADR-0009), PositionClassifier, EquityTracker,
|
||||
│ │ CashFlowDetector, FlattenProcedure, Heartbeat/HeartbeatFile, InstanceLock, RecoveryPlanner
|
||||
│ ├── Baskets/History/ OrderRecord (orders.jsonl), BasketOutcomeRow (baskets.csv), PositionRecord, PeriodStats, CashMovementRecord, EquityPoint, HistoryBuilder (la pagina Storico, pura)
|
||||
│ ├── Broker/ IBroker e modelli (Instrument, QuoteSnapshot, AccountSnapshot, BrokerPosition, ClosedTrade, OrderRequest, OrderOutcome,
|
||||
│ │ CloseOutcome), RateLimiter, LatencyWindow
|
||||
│ ├── Baskets/ SyntheticCross, PipMath, BasketMath, SymbolSeries, BasketDecider, CostGate, VolParitySizing, BasketExecutor, BasketPosition
|
||||
│ │ (con PendingA/PendingB), PendingEntry, BasketStrategyConfig (strategy.json: preset, risk, recovery, learning), BasketSlotPolicy,
|
||||
│ │ ExecutionMode (Demo/Live = conto), OrderTracker (ADR-0009, per conto), PositionClassifier, EquityTracker, StartupCash,
|
||||
│ │ DailyLoss + DailyLossLatch (D-52), FlattenProcedure, Heartbeat/HeartbeatFile, InstanceLock, RecoveryPlanner
|
||||
│ ├── Baskets/History/ OrderRecord (orders.jsonl), BasketOutcomeRow (baskets.csv), PnlCorrections (righe correzione e lettore corretto), PositionMap
|
||||
│ │ (posizioni di una riga per la verifica), PositionOrigins (basket/orfana-bot/esterna), RealizedToday («P&L oggi»),
|
||||
│ │ SettlementQueue (chiusure in attesa dello storico), HistoryBuilder (la pagina Storico, pura)
|
||||
│ ├── Baskets/Data/ BidAskBar + CSV, TickToBars (tick MT5 → M15)
|
||||
│ ├── Baskets/Learning/ CalibrationTables, OnlineLogistic, SmallMlp, ThompsonBandit, VolForecast, LearningFeatures, ModelEvaluator
|
||||
│ ├── Baskets/Backtest/ BasketBacktest, BacktestBroker, BasketTrials
|
||||
│ ├── Baskets/Learning/ OnlineLogistic, SmallMlp, ThompsonBandit, VolForecast, LearningFeatures, ModelEvaluator (+ CalibrationTables), CycleTrainer,
|
||||
│ │ LearningAnalytics, LearningReport, LearningJson (il rapporto di /api/learning e last_cycle.json)
|
||||
│ ├── Baskets/Backtest/ BasketBacktest (con ReplayDailyLoss), BacktestBroker, BasketTrials
|
||||
│ ├── News/ CalendarParser, RssParser, SentimentLexicon, SentimentEngine
|
||||
│ ├── Notifications/ INotifier, NullNotifier, TelegramNotifier (solo HttpClient)
|
||||
│ └── Statistics/ Ols, Normal, Performance (Sharpe, PSR, DSR, drawdown), Classification, Pbo
|
||||
├── src/Encelado.Etoro EtoroOptions, EtoroHttp (x-api-key/x-user-key/x-request-id, limitatore per classe di quota, 429, scarto orologio), EtoroBroker : IBroker, Json
|
||||
│ ├── Notifications/ INotifier, NotifierHub (Telegram acceso, spento o cambiato a caldo), TelegramNotifier (solo HttpClient), TelegramStatus
|
||||
│ ├── Ml/ Classification, Pbo
|
||||
│ └── Statistics/ Ols, Distributions, Performance (Sharpe, PSR, DSR, drawdown)
|
||||
├── src/Encelado.Etoro EtoroOptions, EtoroHttp (x-api-key/x-user-key/x-request-id, limitatore per classe di quota, 429, latenza del solo viaggio
|
||||
│ HTTP, scarto orologio), EtoroBroker : IBroker, Json
|
||||
├── src/Encelado.Engine libreria (net10.0): il motore e tutto ciò che tocca il disco o la rete oltre al broker
|
||||
│ ├── Baskets/ BasketEngine in otto file parziali (.cs ciclo e decisioni, .Pending, .Reconcile, .Kill, .Recovery, .State, .Commands, .Snapshot), Ledger, Feeds,
|
||||
│ │ ContextProvider, LearningState, HistoryService (fonti della pagina Storico, con cache), TelegramReports, TelegramCommands, HeadlessRunner (console: stato, comandi, bonifica)
|
||||
│ ├── Configuration/ BotConfig, ConfigLoader (JsonDocument, variabili d'ambiente), ConfigDefaults (JSON di fabbrica incorporato), ConfigWriter, AppPaths (/config, /data, Documenti), KeyStore (IKeyStore, EncryptedFileKeyStore, KeyStores)
|
||||
│ ├── Engine/ IEngine, BotSupervisor (ciclo di vita, snapshot, eventi di log), BotSnapshot, SnapshotJson (lo snapshot in JSON, a mano), SampleSnapshot (dati finti per --sample e test)
|
||||
│ ├── Logging/ Log statico non bloccante su Channel<T>, file ';' con rotazione, console
|
||||
│ └── Settings/ SettingsCatalogue e SettingField (il form di Impostazioni), SettingsService (descrizione e applicazione via API), UiClock (fuso orario a schermo)
|
||||
│ ├── Baskets/ BasketEngine in undici file parziali (.cs ciclo e decisioni, .Pending, .Reconcile, .Kill, .Recovery, .State, .Commands,
|
||||
│ │ .Realized, .Learning, .View, .Snapshot), AccountStateFiles (stato per conto), Settlements (coda di regolamento), RealizedBackfill
|
||||
│ │ (verifica del realizzato all'avvio), Ledger, Feeds + ContextProvider + ContextRefresher (calendario e notizie in background),
|
||||
│ │ LearningState, LearningCycle (+ CycleRunner), LearningDataset, LearningDiskReader, LearningFiles (AtomicFile, stato
|
||||
│ │ dell'apprendimento), HistoryService (fonti della pagina Storico, con cache), TelegramReports, TelegramCommands, HeadlessRunner
|
||||
│ ├── Configuration/ BotConfig, ConfigLoader (JsonDocument; regola di fusione modalità/ambiente; RemoveObsoleteKeys), ConfigDefaults (JSON di
|
||||
│ │ fabbrica incorporato), ConfigWriter, AppPaths (/config, /data, sandbox, Documenti), InterfacePassword, SecretStore,
|
||||
│ │ EnvironmentImport (importazione una tantum dalla 5.0), KeyStore (solo per leggere il vecchio etoro.keys.enc)
|
||||
│ ├── Engine/ IEngine, BotSupervisor (ciclo di vita), EngineView (la vista pubblicata), ContextView, HealthRules, ReadModel (IBotReadModel,
|
||||
│ │ LiveReadModel), SectionVersions, SnapshotAdapter + BotSnapshot (la fotografia per console e Telegram), SampleData +
|
||||
│ │ SampleReadModel (dati d'esempio per --sample e test), SnapshotJson, SampleSnapshot
|
||||
│ ├── Logging/ Log statico non bloccante su Channel<T>, file ';' con rotazione, console, riconfigurabile a caldo
|
||||
│ └── Settings/ SettingsCatalogue + SettingField (il form di Impostazioni, con file e momento d'effetto), SettingsService (descrizione,
|
||||
│ validazione su copie, scrittura), SettingsRuntime (applicazione a caldo, segreti, AVVIA), AccountActivity (guardia del
|
||||
│ cambio di conto), StrategyCache, AutostartPolicy, UiClock
|
||||
├── src/Encelado.Server l'eseguibile (Microsoft.NET.Sdk.Web, framework reference Microsoft.AspNetCore.App, nessun NuGet)
|
||||
│ ├── Program.cs argomenti e ambiente, AppPaths, log, notifier, supervisore, Telegram, LogBuffer, HistoryService, WebHost, avvio automatico, SIGTERM, --health, --sample
|
||||
│ └── Web/ WebHost (Kestrel, autenticazione, rotte statiche e API), Json (Utf8JsonWriter), LogBuffer (finestra del log per la pagina), LogBridge (log di ASP.NET → Log),
|
||||
│ wwwroot/ (index.html, login.html, app.css, app.js, icon.svg, manifest.webmanifest — incorporati)
|
||||
├── tools/Encelado.Backtest ticks, baskets, falsify, learn (referenzia Core ed Engine)
|
||||
│ ├── Program.cs password, configurazione, segreti, importazione, log, feed, notifier, supervisore, impostazioni, WebHost, avvio
|
||||
│ │ automatico, SIGTERM, --health, --sample, --listen-all
|
||||
│ ├── SampleFolders.cs le cartelle temporanee di --sample (create all'avvio, cancellate all'uscita)
|
||||
│ └── Web/ WebHost (Kestrel, RequestGuard, autenticazione, rotte), AuthBackoff (attesa dopo una password errata), SnapshotHub (un tick al
|
||||
│ secondo per tutti), TickWriter (tick v2), SectionJson + SectionCache (sezioni a richiesta con ETag), SystemJson (+ DiskProbe),
|
||||
│ SettingsApi, StaticFiles, Json (Utf8JsonWriter), LogBuffer (finestra del log con seq), LogBridge (log di ASP.NET → Log),
|
||||
│ wwwroot/ (index.html, login.html, css/, js/, js/pages/, icon.svg, manifest.webmanifest — incorporati)
|
||||
├── tools/Encelado.Backtest ticks, baskets, falsify, learn (referenzia Core ed Engine; learn prende il lock di istanza)
|
||||
├── tests/Encelado.Tests xunit (net10.0, gira su Windows e nello stadio di build dell'immagine)
|
||||
├── .gitea/workflows/ ci.yml (build, test, docker build a ogni push), release.yml (immagine sul registro e release a ogni tag)
|
||||
├── deploy/docker/ entrypoint.sh (TZ, PUID/PGID, gosu, exec)
|
||||
├── deploy/unraid/ encelado.xml (template Container v2), README.md
|
||||
├── deploy/unraid/ encelado.xml (template Container v2: porta, /config, /data, ENCELADO_PASSWORD), README.md
|
||||
├── deploy/local/ sandbox ignorata da git: /config e /data delle prove sul PC (F5, run-dev, compose)
|
||||
├── scripts/ run-dev, run-docker, screenshots (.ps1 e .sh), cdp-shot.mjs
|
||||
├── Dockerfile, docker-compose.yml, .dockerignore
|
||||
└── build/ Release.proj (Verifica, Backtest, Pubblica, Docker, Pacchetto, Rilascia), README.md
|
||||
```
|
||||
|
||||
- **Target framework**: `net10.0` ovunque, `Nullable` e `TreatWarningsAsErrors` attivi via `Directory.Build.props`; `InvariantGlobalization` nei progetti dell'applicazione (i test lo spengono per verificare i fusi IANA e Windows). SDK 10.0.301.
|
||||
- **Pattern**: nessun contenitore DI; oggetti costruiti a mano in `Program.cs` e nel supervisore; async/await con `ConfigureAwait(false)` nel motore; `Channel<T>` per il log e le notifiche; `Lock` per lo stato condiviso; snapshot immutabili verso il server; ogni tabella è CSV `;` con colonna finale `motivazione`; log strutturato `timestamp;level;source;subject;event;message;exception;stack`.
|
||||
- **Storage**: solo file (ADR-0002). Nel container `/config` (configurazione, chiavi cifrate) e `/data` (`data/`, `knowledge/`, `reports/`, `results/`, `logs/`); fuori dal container `Documenti\Encelado` o `ENCELADO_CONFIG_DIR`.
|
||||
- **Target framework**: `net10.0` ovunque, `Nullable` e `TreatWarningsAsErrors` attivi via `Directory.Build.props` (che porta anche la versione di sviluppo, 5.1.0); `InvariantGlobalization` nei progetti dell'applicazione (i test lo spengono per verificare i fusi IANA e Windows). SDK 10.0.301.
|
||||
- **Pattern**: nessun contenitore DI; oggetti costruiti a mano in `Program.cs` e nel supervisore; async/await con `ConfigureAwait(false)` nel motore; `Channel<T>` per il log e le notifiche; `Lock` per lo stato condiviso; viste immutabili pubblicate verso il server; ogni tabella è CSV `;` con colonna finale `motivazione`; log strutturato `timestamp;level;source;subject;event;message;exception;stack`.
|
||||
- **Storage**: solo file (ADR-0002). Nel container `/config` (configurazione, segreti cifrati, file `STOP`) e `/data` (`data/`, `knowledge/`, `reports/`, `results/`, `logs/`); fuori dal container la sandbox `deploy/local/` (`ENCELADO_CONFIG_DIR` + `ENCELADO_DATA_DIR`) o `Documenti\Encelado`.
|
||||
- **Build ed esecuzione**: `dotnet build Encelado.slnx`; `dotnet run --project src/Encelado.Server`; immagine con `dotnet msbuild build/Release.proj -t:Docker`; la versione rilasciata viene dal tag git, commit e data di build da `AssemblyMetadata`.
|
||||
|
||||
## 2. Flusso dati (live)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
E[eToro Public API] -->|rates ogni 3 s| Q[Quote poller]
|
||||
E[eToro Public API] -->|rates ogni pollSeconds| Q[Quote poller]
|
||||
Q --> B[Bar builder M15]
|
||||
E -->|candles| B
|
||||
B --> S[Strategy loop<br/>un solo thread]
|
||||
C[Calendario + RSS] --> F[Feature contesto]
|
||||
B --> S[Ciclo di decisione<br/>un solo thread]
|
||||
C[Calendario + RSS<br/>in background, del processo] --> F[ContextView]
|
||||
F --> S
|
||||
M[Meta-modello in ombra<br/>vol forecast] --> S
|
||||
S -->|decisione| X[Executor<br/>leg-risk + OrderTracker]
|
||||
X --> E
|
||||
E -->|storico posizioni chiuse| R[Coda di regolamento<br/>realizzato, P&L oggi]
|
||||
R --> S
|
||||
S --> L[(Ledger jsonl/csv)]
|
||||
X --> L
|
||||
S --> N[Snapshot]
|
||||
N --> W[Server: SSE /api/stream<br/>console, Telegram]
|
||||
S -->|Volatile.Write| V[EngineView<br/>vista pubblicata]
|
||||
V --> H[SnapshotHub<br/>un tick al secondo]
|
||||
H --> W[SSE /api/stream]
|
||||
V --> D[Sezioni a richiesta<br/>ETag/304]
|
||||
W --> U[Browser]
|
||||
U -->|POST /api/commands| W --> S
|
||||
L --> K[Ciclo di apprendimento<br/>backtest learn / Ricerca]
|
||||
K --> M
|
||||
D --> U
|
||||
V --> T[Console, Telegram]
|
||||
U -->|POST /api/commands, /api/settings| P[Supervisore e impostazioni]
|
||||
P -->|comandi sul thread di decisione| S
|
||||
L --> K[Ciclo di apprendimento<br/>in background]
|
||||
K -->|applicato fra due tick| M
|
||||
```
|
||||
|
||||
Le decisioni avvengono su un solo thread; l'I/O è asincrono; l'unico gate umano per ordine è sparito (ADR-0005): restano avvio del reale, kill-switch, reset e cambio di preset, tutti dall'interfaccia web, dalla console o da Telegram.
|
||||
Le decisioni avvengono su un solo thread; l'I/O è asincrono; nessuno approva il singolo ordine (ADR-0005): i gate umani sono l'avvio del reale, il kill-switch e il reset, dall'interfaccia web, dalla console o da Telegram.
|
||||
|
||||
## 3. Macchina a stati del basket
|
||||
## 3. Macchine a stati
|
||||
|
||||
### Il basket
|
||||
|
||||
```
|
||||
Idle ──(segnale + cancelli)──► Entering ──(A e B eseguite)──► Open ──(add)──► Adding ──► Open
|
||||
@@ -85,44 +116,81 @@ Idle ──(segnale + cancelli)──► Entering ──(A e B eseguite)──
|
||||
Error (blocco nuove entrate finché non risolto)
|
||||
```
|
||||
|
||||
Stati del motore (non del basket): `Halted` dopo un kill-switch o un equity stop con il conto piatto per le posizioni del bot; **`Halted-Residuo`** quando la verifica di piattezza trova ancora posizioni del bot sul conto (banner rosso con l'elenco, reset rifiutato finché restano). Negli stati `PendingA`/`PendingB` il basket non viene valutato e non manda ordini; il registro degli ordini (`OrderTracker`) chiede l'esito al server e, quando manca, lo ricostruisce dalla posizione comparsa sul conto. Gli ingressi in sospeso sopravvivono a un riavvio (`pendingEntries` in `baskets_state.json`) e vengono risolti all'avvio prima di qualsiasi decisione.
|
||||
Stati del motore (non del basket): `Halted` dopo un kill-switch o un equity stop con il conto piatto per le posizioni del bot; **`Halted-Residuo`** quando la verifica di piattezza trova ancora posizioni del bot sul conto (o un kill-switch è stato interrotto dall'arresto del processo): allarme con l'elenco, reset rifiutato finché restano. Negli stati `PendingA`/`PendingB` il basket non viene valutato e non manda ordini; il registro degli ordini (`OrderTracker`) chiede l'esito al server e, quando manca, lo ricostruisce dalla posizione comparsa sul conto. Gli ingressi in sospeso sopravvivono a un riavvio (`pendingEntries` nello stato del conto) e vengono risolti all'avvio prima di qualsiasi decisione. Un basket spento in Impostazioni continua a gestire le uscite di ciò che ha sul conto (`BasketSlotPolicy`).
|
||||
|
||||
### Il supervisore
|
||||
|
||||
`stopped` → `starting` → `running` → `stopping` → `stopped`, oppure `faulted` quando l'avvio fallisce o il ciclo del motore finisce senza che nessuno l'abbia fermato. Un motore in errore viene rilasciato (lock di istanza compreso) prima di un nuovo avvio o di una manutenzione dell'apprendimento. Vedi §5.
|
||||
|
||||
## 4. Interfacce
|
||||
|
||||
- `IBroker`: `Environment`, `GetInstrumentsAsync`, `GetQuotesAsync(ids)`, `GetCandlesAsync(id, interval, count)`, `GetAccountAsync`, `GetPositionsAsync`, `OpenAsync(OrderRequest)` (esito per `orderId`, poi per posizione comparsa; mai un esito inventato), `LookupOrderAsync(clientRef)`, `LookupOrderByIdAsync(orderId)`, `CancelOrderAsync(orderId)`, `CloseAsync(positionId, instrumentId)`, `UpdateStopsAsync(positionId, sl, tp)`, `GetCostAsync(OrderRequest)`, `GetClosedTradesAsync`, `ClockSkew`.
|
||||
- `IContextProvider` (Engine): calendario, notizie e sentiment per basket (`FeedContextProvider`).
|
||||
- `IBroker`: `Environment`, `GetInstrumentsAsync`, `GetQuotesAsync(ids)`, `GetCandlesAsync(id, interval, count)`, `GetAccountAsync`, `GetPositionsAsync`, `OpenAsync(OrderRequest)` (esito per `orderId`, poi per posizione comparsa; mai un esito inventato), `LookupOrderAsync(clientRef)`, `LookupOrderByIdAsync(orderId)`, `CancelOrderAsync(orderId)`, `CloseAsync(positionId, instrumentId)` (`CloseOutcome` con `PositionId`, `Proceeds` e `ConversionRate` solo per diagnostica e stima; `RealizedPnl` è NaN per eToro: il realizzato viene dallo storico), `UpdateStopsAsync(positionId, sl, tp)`, `GetCostAsync(OrderRequest)`, `GetClosedTradesAsync` (lancia un errore su HTTP fallito, mai un elenco vuoto), `ClockSkew`.
|
||||
- `IContextProvider` (Engine): calendario, notizie e sentiment per basket (`FeedContextProvider`), con la fotografia immutabile `ContextView`; appartiene al processo e si aggiorna in background (`ContextRefresher`) anche a motore fermo.
|
||||
- `IModel`: `Predict(features)`, `Update(features, label)`, JSON, implementato da `OnlineLogistic` e `SmallMlp`.
|
||||
- `IEngine` (Engine): `RunAsync`, `CloseAllAsync`, `ExecuteAsync(EngineCommand)` con `Close`, `KillSwitch` (argomento `esterne`), `SetPreset`, `ResetEquityStop(motivazione)` (la procedura in cinque passi), `CloseResidue`, `Bonifica`, `History`, `Pause`, `Resume`, `Snapshot()`. Ogni comando eseguito è una riga `comando` nel ledger.
|
||||
- `INotifier` (Core): `Notify(kind, title, text)` non bloccante e `Status`; il motore lo riceve dal supervisore, che lo riceve da `Program.cs` (`Notifications.Create`).
|
||||
- `IKeyStore` (Engine): `Load(demo)`, `Save`, `Clear`, `CanSave`, implementato da `EncryptedFileKeyStore` (`etoro.keys.enc`, AES-256-GCM con passphrase); le variabili `ETORO_API_KEY`/`ETORO_USER_KEY` le applica il loader e `KeyStores.Resolve` prova prima quelle poi il file.
|
||||
- `WebContext` (Server): ciò che il web host vede del processo — configurazione, supervisore, finestra del log, storico, percorso del file, `Start` e `Learn` come funzioni, `Snapshot()` (finto in `--sample`).
|
||||
- `IEngine` (Engine): `RunAsync`, `ExecuteAsync(EngineCommand)`, `View` (l'ultima `EngineView` pubblicata), `Learning` (l'ultimo rapporto dell'apprendimento), `LoopStarted` (il ciclo di decisione è partito: prima, «Esegui ciclo» e il cambio di conto rispondono 409). Comandi (`EngineCommandKind`): `Close`, `KillSwitch` (argomento `esterne`, `solo-bot` o vuoto = vale l'impostazione), `ResetEquityStop` (la procedura in cinque passi), `CloseResidue`, `Bonifica`, `History`, `Pause`, `Resume`, `ApplySettings`, `Learn`, `Shutdown` (argomento `chiudi`: la chiusura all'arresto con `run.closeOnShutdown`), `PrepareAccountSwitch` e `CancelAccountSwitch` (la guardia del cambio di conto). Ogni comando eseguito, o interrotto da un arresto, è una riga `comando` nel ledger. Non esiste più nessun metodo del motore chiamato da un altro thread (`CloseAllAsync` è privato; il comando `preset` non esiste più).
|
||||
- `INotifier` (Core): `Notify(kind, title, text)` non bloccante e `Status`; `NotifierHub` lo implementa e scambia a caldo il canale nullo con quello Telegram (token dal deposito dei segreti, poller dei comandi acceso e spento) quando cambiano le impostazioni.
|
||||
- `IBotReadModel` (Engine): ciò che il web legge — la vista del motore (`EngineStatus`: stato, vista viva, ultima vista dopo l'arresto), il contesto, Telegram, i segreti, l'apprendimento —, implementato da `LiveReadModel` (il processo vero) e `SampleReadModel` (`--sample`).
|
||||
- `WebContext` (Server): configurazione, supervisore, finestra del log, storico, percorso del file, `SettingsRuntime`, la funzione di avvio, il provider del contesto e lo stato di Telegram; `Read` è il modello di lettura, `Strategy()` la strategia in cache (quella di fabbrica in `--sample`).
|
||||
|
||||
## 5. API web
|
||||
## 5. Thread, viste e ciclo di vita (ADR-0012)
|
||||
|
||||
Tutte le rotte tranne `/api/health`, `/login`, `/icon.svg`, `/manifest.webmanifest` chiedono il token (`ENCELADO_WEB_TOKEN`) nel cookie `encelado_token` (HttpOnly, 30 giorni) o in `Authorization: Bearer`. Senza token configurato il server ascolta solo su localhost e non chiede niente. JSON scritto a mano con `Utf8JsonWriter`, mai serializzazione per reflection.
|
||||
- **Un solo thread tocca il motore.** Il ciclo di decisione pubblica un'`EngineView` immutabile con `Volatile.Write` all'avvio, dopo ogni giro, ogni lettura delle quotazioni, ogni transizione, lo smaltimento dei comandi e ogni riconciliazione: per basket valutazione, decisione con costo e size, contesto, feature del meta-modello, volatilità, posizione con le gambe e i numeri del conto, ingresso in attesa, le ultime 20 decisioni di chiusura barra; quotazioni con mediana 24 h e ATR, cambi con la coppia d'origine, posizioni classificate, registro degli ordini, quote HTTP, allarmi, conto e giornata, intervallo dell'heartbeat. Costruirla non ha effetti collaterali (`VolForecaster.Stats/Describe` sono letture pure). Web, console (`SnapshotAdapter` → `BotSnapshot`) e Telegram leggono solo quella. Tutto ciò che cambia il motore è un `EngineCommand` eseguito sul thread di decisione.
|
||||
- **SnapshotHub**: un `PeriodicTimer` di 1 s costruisce il tick (`TickWriter`) **una volta** per tutti i client SSE e manda gli stessi byte; senza client non costruisce niente; ogni client ha un canale di un frame che tiene il più recente (un client lento non rallenta gli altri); il primo frame parte subito, con `retry: 3000`. `/api/snapshot` risponde con lo stesso tick. Un iscritto il cui primo frame fallisce viene tolto subito.
|
||||
- **Sezioni a richiesta**: `/api/positions`, `/api/market`, `/api/baskets/detail`, `/api/system`, `/api/learning` hanno `ETag` e 304 (`SectionCache`, con età massime di 30, 15, 2 e 2 s); `SectionVersions` (motore, supervisore, impostazioni, tick per firma) dice al browser quando rileggerle (`versions` nel tick).
|
||||
- **Lucchetto del ciclo di vita** (`BotSupervisor`, revisione 5.1): un solo `SemaphoreSlim` serializza `StartAsync`, `StopAsync`, `ShutdownAsync`, `RestartAsync`, il rilascio di un motore in errore e la manutenzione dell'apprendimento, ciascuno dal primo controllo all'ultimo cambio di stato. Ogni avvio ha un numero di generazione: la fine del ciclo di un motore e la fine di un arresto cambiano stato e campi solo per la loro generazione e non scrivono mai sopra `stopping`. Lo stato resta `stopping` finché il motore vecchio non è stato smaltito e ha liberato `instance.lock`: un AVVIA arrivato nel frattempo aspetta invece di fallire. I **comandi critici** (kill-switch, chiusura, chiusura dei residui, chiusura della bonifica: `EngineCommand.IsCritical`) li conta il motore stesso (`IEngine.CriticalCommand`) dalla coda finché il thread di decisione non li ha conclusi, o finché la sua esecuzione non finisce senza prenderli — non finché chi li ha chiesti aspetta (seconda revisione: una scheda chiusa, un poller Telegram fermato o un 504 dopo 120 s liberavano FERMA a metà kill-switch); il supervisore aggiunge quelli che sta inoltrando (`CommandInProgress`). FERMA, un riavvio automatico e le chiavi del conto in uso rispondono 409 finché durano.
|
||||
- **Arresto**: con `run.closeOnShutdown` il supervisore manda il comando `Shutdown` (`chiudi`): il motore blocca nuove entrate e aggiunte, chiude basket, gambe in attesa e orfane sul suo thread entro `ShutdownBudget` (30 s), e solo dopo il ciclo viene annullato. All'arresto del processo (`ShutdownAsync`, mai rifiutato) un kill-switch in corso ha gli stessi 30 s; se non basta, le posizioni note del bot diventano il residuo (`kill_switch_interrotto`, Halted-Residuo). Annullamento, attesa (al più 45 s), smaltimento e stato finale stanno in un `finally`: un arresto non resta mai bloccato in `stopping`. La coda dei comandi del motore si chiude alla fine del suo `RunAsync` (anche quando l'avvio fallisce) e risponde subito «comando interrotto: il motore si è fermato» a tutto ciò che restava; un'attesa scaduta sul web è 504, mai 500.
|
||||
- **Heartbeat e salute**: `HealthRules` dà le parole delle icone (API, feed, Telegram) e il giudizio di `/api/health`: a motore acceso l'heartbeat è vecchio oltre 3 × `heartbeatSeconds` + 15 s; la prova di scrittura del disco (`DiskProbe`) si ripete al più una volta al minuto.
|
||||
|
||||
## 6. Impostazioni, segreti e accesso (ADR-0010)
|
||||
|
||||
- **Catalogo** (`SettingsCatalogue`): sette gruppi — `conto`, `esecuzione`, `strategia`, `avanzate` (chiuso), `telegram`, `interfaccia`, `log` —; ogni campo dice in che file vive (`encelado.json` o `strategy.json`, prefisso `strategy:`), il tipo (testo, numero, intero, scelta, sì/no, elenco) e quando ha effetto (`SettingScope`): `immediate` nel processo (log, interfaccia, Telegram), `engine` nel motore in esecuzione sul suo thread (strategia, intervalli, timeout), `restart` con un riavvio automatico del motore che non chiude niente (modalità/conto, chiavi del conto attivo, coppie dei basket, `preferDirectCross`).
|
||||
- **Salvataggio** (`SettingsRuntime.ApplyAsync`, un lock di scrittura): validazione su copie dei due file (con l'overlay vero e la stessa scrittura che verrà fatta: `ConfigLoader.RemoveObsoleteKeys` scrive la modalità che il file intendeva quando `etoro.environment` esce), scrittura atomica di `strategy.json` e poi di `encelado.json` (`ConfigWriter`, encoder rilassato, chiavi cancellate, righe `_` di documentazione aggiornate), `BotConfig.CopyFrom` in memoria, poi l'effetto: hook del processo (`Log.Reconfigure`, `LogBuffer.Resize`, `NotifierHub`, `HistoryService.Invalidate`), comando `ApplySettings` al motore (`BasketStrategyConfig.CopyFrom`, `BasketDecider.Reload`, nuovo hash, riga `configurazione` nel ledger), oppure `BotSupervisor.RestartAsync`, che sotto il lucchetto del ciclo di vita rilegge lo stato e riavvia solo un motore ancora acceso. Live: 409 `needsPhrase` prima di scrivere. La risposta dice per ogni campo `immediate`/`engine`/`restart`/`stored`/`error`.
|
||||
- **Cambio di conto** (C8, D-53): a motore acceso `BotSupervisor.PrepareAccountSwitchAsync` manda `PrepareAccountSwitch`; il motore blocca le entrate (`_switchBlock`, controllato anche negli ingressi e nelle aggiunte), riconcilia con il conto (lo stesso passo del ciclo: una gamba del bot che nessuno slot tiene diventa un'orfana e conta; posizioni non lette → rifiuto, `AccountUnread`) e conta sui propri slot (`AccountActivity.FromEngine`); occupato → il blocco si toglie e la risposta elenca cosa c'è; libero → le entrate restano bloccate fino al riavvio. Dopo l'arresto, nel gancio `beforeStart` di `RestartAsync`, il file del conto lasciato si giudica di nuovo (`AccountActivity.FromDisk`); se non è piatto, o è partito un comando critico, i due file delle impostazioni tornano byte per byte come prima e niente riparte. A motore fermo decide `AccountActivity.FromDisk` sul conto in uso. `CancelAccountSwitch` toglie il blocco su ogni percorso in cui il cambio non avviene.
|
||||
- **Segreti** (`SecretStore`, `/config/secrets.enc`): chiavi eToro dei due conti e token Telegram, AES-256-GCM con chiave PBKDF2-SHA256 (600 000 iterazioni) dalla password; formato `ENC2` | sorgente della chiave | iterazioni | sale | nonce | tag | testo cifrato, intestazione autenticata; iterazioni fuori da 100 000-10 000 000 = file danneggiato. Stati `empty`, `open`, `locked` (password cambiata: sblocco con la precedente o ripartenza con un `.bak`), `localKey` (senza password: chiave casuale in `secrets.key`, sostituita dalla password appena compare). Motore e storico ricevono una copia privata delle chiavi (`EtoroOptions`), mai la configurazione condivisa.
|
||||
- **Importazione una tantum** (`EnvironmentImport`, `import-5.1.json`): le variabili e i file di un container 5.0 passano nel deposito e in `encelado.json`, poi le variabili rimaste vengono ignorate ed elencate (log, Sistema, `alarms.ignoredEnv`). Il caricatore della configurazione non legge più l'ambiente.
|
||||
- **Password e accesso** (`InterfacePassword`, `WebHost`): `ENCELADO_PASSWORD` (alias deprecato `ENCELADO_WEB_TOKEN`); cookie `encelado_session` = Base64Url(HMAC-SHA256(SHA-256("encelado/cookie/v2" ‖ segreto ‖ password), "session")), con il segreto del server in `<config>/session.key` (`SessionKey`, 32 byte casuali creati una volta), HttpOnly, SameSite=Strict, 30 giorni; `Authorization: Bearer` per gli script; confronti a tempo costante. Prima dell'autenticazione `RequestGuard` rifiuta ciò che viene da altrove: senza password ogni `Host` che non sia `localhost`/`127.0.0.1`/`[::1]` (403, DNS rebinding); per ogni metodo diverso da GET/HEAD/OPTIONS un `Sec-Fetch-Site` di un'altra origine o un `Origin` con un altro host:porta (403; `/login` e `/logout` solo l'`Origin`; `X-Forwarded-Host` per i reverse proxy); sotto `/api/` un `Content-Type` diverso da `application/json` (415). `AuthBackoff` fa pagare ogni password errata (form, Bearer) all'indirizzo del client (IPv6 per /64): 1, 2, 4, 8, 16, poi 30 s, con 429 a ogni richiesta con una password durante l'attesa. Il cookie si controlla prima e fuori da lì (seconda revisione): valido entra anche durante l'attesa e non azzera il conto, sbagliato riceve 401 subito. Il server ascolta su tutte le interfacce solo con la password e nel container (`AppPaths.InContainer`) o con `--listen-all` (`WebHost.ListensOnTheNetwork`); altrimenti su localhost.
|
||||
- **`--sample`**: `SampleFolders` crea `%TEMP%/encelado-campione-<pid>-<guid>/{config,data}` e `AppPaths.UseFolders` ci punta; niente importazione, niente canale Telegram, niente feed; `SampleReadModel` serve dati d'esempio coerenti per ogni rotta; ogni comando e ogni scrittura di impostazioni o segreti risponde 400. Le cartelle si cancellano all'uscita, e quelle di processi campione morti al prossimo avvio campione.
|
||||
|
||||
## 7. Realizzato, rischio e stato per conto (ADR-0011, D-52, D-53)
|
||||
|
||||
- **Coda di regolamento** (`Settlements` + `SettlementQueue`, persistita come `pendingSettlements`): ogni chiusura (basket, gamba singola, orfana, residuo, chiusura del broker, gamba richiusa) entra con la stima dai prezzi di chiusura; la riga di `baskets.csv` si scrive quando lo storico eToro mostra tutte le sue posizioni (`netProfit − fees`), oppure dopo 30 minuti con la stima marcata, che non addestra niente. Una posizione già registrata (marcatore `posizioni:` delle righe del conto) o già in coda non viene registrata di nuovo da nessun percorso (`IsRecorded`); il residuo del kill-switch si pota alla riconciliazione delle posizioni che il conto non mostra più.
|
||||
- **Storico eToro** (`RefreshRealizedAsync`, una lettura condivisa): circa ogni 5 minuti, ogni 5 s nel minuto dopo una chiusura, ogni 30 s finché una chiusura attende. Serve la coda, «P&L oggi» (`RealizedToday`, pubblicato in modo atomico, uguale al periodo «oggi» dello Storico grazie alla stessa classificazione `PositionOrigins`) e il giudizio sui movimenti di cassa (`EquityTracker`, che non giudica finché lo storico non mostra le chiusure).
|
||||
- **Perdita giornaliera**: `DailyLoss.IsHit` sull'equity netta dalla mezzanotte UTC, valutata a ogni lettura del conto e a ogni decisione; `DailyLossLatch` tiene il blocco fino alle 00:00 UTC (salvato come `dailyLossDay`); un calo del saldo non ancora spiegato dallo storico sospende le entrate senza chiudere la giornata (D-54): il motore ricorda l'equity più bassa vista nel frattempo, la vista lo dice in `DailyLossHit` anche se l'equity recupera, e la lettura che lo spiega giudica la giornata su quel minimo (una perdita la blocca, un movimento di cassa no; seconda revisione). Il backtest usa la stessa regola (`ReplayDailyLoss`). Vista: `FundsView.DailyLossLatched`, tick `dailyLossLatched`.
|
||||
- **Saldo all'avvio** (`StartupCash`): il saldo salvato si giudica solo quando lo storico mostra ogni posizione chiusa da allora (`lastPositionIds`, `vanishedUnsettled`, coda); altrimenti resta il riferimento e giudica la riconciliazione.
|
||||
- **Verifica del realizzato all'avvio** (`RealizedBackfill`, `PositionMap`): righe della 4.0.0-5.0.0 del conto in uso, soglia per conto, abbinamento globale delle note delle gambe singole; righe `correzione` nuove, mai una riga modificata; poi `LearningState.Reseed` e, una volta sola, il ritiro dei modelli addestrati sui proceeds.
|
||||
- **Stato per conto** (`AccountStateFiles`): `data/state/baskets_state.demo.json` e `.live.json`; migrazione una tantum del file unico della versione precedente (sotto il lock di istanza, `LegacyTarget`): un file della 5.1 va al conto del suo `mode`; uno della 5.0, dove `mode` era la modalità e non il conto, va al conto su cui operava la configurazione della 5.0 (`LegacyStateOwner`, registrato dall'importazione in `import-5.1.json`), senza registrazione solo al conto del motore che lo trova se nomina la sua modalità; Paper, o una modalità diversa da quella della configurazione registrata, resta solo come `.migrato`, mai letto. Un file dell'altro conto non viene mai letto né scritto. Il registro degli ordini (`OrderTracker(path, account)`) è un file solo ma ogni motore lavora solo sui suoi ordini.
|
||||
- **Kill-switch** (`FlattenProcedure` + `KillAsync`): la scelta esplicita sulle posizioni esterne (`EngineCommand.ForeignChoice`) vince su `risk.closeForeignOnKill`.
|
||||
|
||||
## 8. Apprendimento (ADR-0006, ADR-0014)
|
||||
|
||||
- **Un solo scrittore** di `data/models` e `knowledge/`: chi tiene `instance.lock`. `LearningState` si costruisce dopo il lock e si salva sotto il suo lock prima di rilasciarlo.
|
||||
- **Ciclo** = `LearningCycle.Train`, funzione pura in background che legge il ledger in condivisione (`LearningDataset`: righe con `FileShare.ReadWrite|Delete`, cache per file) e restituisce tutto; `CycleRunner` ne fa girare uno alla volta; `LearningState.Apply` lo applica sul thread di decisione in pochi millisecondi (modelli sostituiti, basket chiusi nel frattempo rigiocati, file scritti con `AtomicFile`, `last_cycle.json`).
|
||||
- **«Esegui ciclo»** (`BotSupervisor.RunLearningCycleAsync`): comando `Learn` al motore acceso; manutenzione sotto il lock a motore fermo (AVVIA 409 finché dura); 409 con un ciclo in corso, con il motore che si avvia (`LoopStarted` falso) o si ferma, o con il lock di un altro processo. Il ciclo settimanale usa lo stesso percorso.
|
||||
- **Rapporto**: a motore acceso `LearningLiveReport` pubblicato dal thread di decisione (chiusura di barra e di basket, ciclo, comandi, avvio, ogni 60 s); a motore fermo `LearningDiskReader` legge i file in sola lettura (mai un `Ledger` o un `LearningState`), tiene l'ultima lettura buona di un file illeggibile e ricalcola il dataset appena compare una correzione; `LearningReportBuilder` compone `/api/learning`. Ogni `p_ML` viaggia con la sua spiegazione (`ScoreExplanation`: p, intercetta, contributi), salvata con l'ingresso.
|
||||
|
||||
## 9. API web
|
||||
|
||||
Il contratto completo (campi, tipi, codici HTTP) è `docs/API.md`. Libere senza sessione: `/login`, `/logout`, `/api/health`, `/css/*`, `/img/*`, `/icon.svg`, `/manifest.webmanifest`. JSON scritto a mano con `Utf8JsonWriter`, mai serializzazione per riflessione.
|
||||
|
||||
| Rotta | Cosa |
|
||||
|---|---|
|
||||
| `GET /`, `/index.html`, `/app.css`, `/app.js`, `/icon.svg`, `/manifest.webmanifest`, `/login`; `POST /login` | la pagina e i suoi file, incorporati; il login mette il cookie e rimanda a `/` |
|
||||
| `GET /api/health` | `{ok, running, heartbeatAgeSeconds, disk, state}`; usato dal `HEALTHCHECK` del container |
|
||||
| `GET /api/snapshot` | lo snapshot completo (`SnapshotJson`) |
|
||||
| `GET /api/stream` | Server-Sent Events, `event: snapshot` con lo stesso JSON, uno al secondo |
|
||||
| `GET /api/log?level=&q=&limit=&after=` | la finestra del log (`LogBuffer`), a incrementi per `seq` |
|
||||
| `POST /api/commands/{start\|stop\|close\|kill\|preset\|reset\|residue\|pause\|resume\|bonifica\|learn}` | corpo `{argument, reason, confirm, foreign}`; risposta `{ok, message, steps[], positions[]}` |
|
||||
| `GET /`, `/login`, ogni file sotto `wwwroot/` (`/css/…`, `/js/…`, `/js/pages/…`); `POST /login`, `POST /logout` | la pagina e i suoi file, incorporati, con `ETag` e 304; il login mette il cookie e rimanda a `/`, il logout lo toglie |
|
||||
| `GET /api/health` | `{ok, state, apiState, heartbeatAgeSeconds, heartbeatSeconds, diskWritable, uptimeSeconds}`; usato dal `HEALTHCHECK` del container |
|
||||
| `GET /api/stream`, `GET /api/snapshot` | il tick v2 (SSE, uno al secondo condiviso; oppure una volta) |
|
||||
| `GET /api/positions`, `/api/market`, `/api/baskets/detail?name=`, `/api/system` (alias `/api/info`), `/api/learning` | le sezioni a richiesta, con `ETag` |
|
||||
| `GET /api/log?level=&q=&limit=&after=` | la finestra del log (`LogBuffer`), una riga per messaggio, a incrementi per `seq` |
|
||||
| `POST /api/commands/{start\|stop\|close\|kill\|reset\|residue\|pause\|resume\|bonifica\|learn}` | corpo `{argument, reason, confirm, foreign}`; risposta `{ok, message, needsPhrase, code?, steps[], positions[]}`; 409 `needsPhrase`/`refused`, 504 `timeout` |
|
||||
| `GET /api/history/orders\|positions\|periods[?format=csv&from=&to=&basket=&symbol=&outcome=&origin=]` | le tre viste dello Storico (`HistoryBuilder`); `format=csv` scarica il file `;` |
|
||||
| `GET/POST /api/settings` | il form (`SettingsService.Describe`) e le modifiche per percorso (`Apply`, con validazione e scrittura atomica) |
|
||||
| `POST/DELETE /api/settings/keys` | verifica le chiavi contro eToro (profilo e conto) e le salva nel file cifrato; rimozione |
|
||||
| `POST /api/settings/restore` | configurazione ai valori di fabbrica con backup datato (solo a bot fermo) |
|
||||
| `GET /api/info` | nome, autore, versione, data di build, commit, percorsi, .NET, sistema, uptime, quote, fuso |
|
||||
| `GET /api/research` | stato dell'apprendimento (abilitazioni, modello in ombra, bandit, volatilità, file in `knowledge/`) |
|
||||
| `GET/POST /api/settings` | il form (gruppi, campi, segreti, versione) e il salvataggio per percorso, applicato a caldo |
|
||||
| `POST/DELETE /api/settings/keys`, `POST/DELETE /api/settings/telegram-token`, `POST /api/settings/telegram-test`, `POST /api/settings/secrets/unlock`, `POST /api/settings/secrets/reset`, `POST /api/settings/restore` | segreti (verificati contro eToro o Telegram e cifrati), sblocco o ripartenza del deposito, valori di fabbrica |
|
||||
|
||||
Il ciclo di vita del processo (`Program.cs`): carica `AppPaths` (semina `encelado.json` e `strategy.json`), inizializza il log (file + console), crea notifier e supervisore, avvia Kestrel, avvia il motore se `ENCELADO_AUTOSTART` ≠ 0 (chiavi da `KeyStores.Resolve`, frase `CONFERMO LIVE` per il Live), legge i comandi da stdin, si ferma su Ctrl+C, SIGTERM, `stop` o `--minutes`. `--health` interroga `/api/health` ed esce 0/1; `--sample` serve dati finti senza motore; `--bonifica` avvia con la bonifica interattiva.
|
||||
Il ciclo di vita del processo (`Program.cs`): risolve la password; in `--sample` crea le cartelle temporanee; carica `AppPaths` (semina `encelado.json` e `strategy.json`); inizializza il log (file + console); apre il deposito dei segreti; esegue l'importazione una tantum dalla 5.0 ed elenca le variabili ignorate; crea il provider dei feed, il `NotifierHub`, il supervisore, `HistoryService` e `SettingsRuntime`; avvia Kestrel (rete solo nel container o con `--listen-all`); decide l'avvio automatico (`AutostartPolicy`: mai in Live, che aspetta AVVIA con la frase e manda un avviso; mai con `--no-autostart` o `run.autostart` spento); legge i comandi da stdin; a motore fermo tiene aggiornati i feed; si ferma su Ctrl+C, SIGTERM, `stop` o `--minutes` con `ShutdownAsync`. `--health` interroga `/api/health` ed esce 0/1; `--bonifica` avvia con la bonifica interattiva.
|
||||
|
||||
## 6. Vincoli e limiti dell'API eToro
|
||||
## 10. Vincoli e limiti dell'API eToro
|
||||
|
||||
- L'endpoint candele accetta solo `count ≤ 1000` senza data di partenza: dà al massimo ~10 giorni di M15. Lo storico per il backtest viene dai tick MT5 forniti dall'utente (`A:\Download\Trading`, 2018-12 → 2026-09, UTC), convertiti in M15 bid/ask dallo strumento `backtest ticks`.
|
||||
- Quote di mercato (`/api/v2/market-data/rates`) in batch fino a 1000 strumenti per chiamata: un polling ogni 3 s costa 20 richieste/min sulla quota condivisa di 120/min. Le sette coppie di conversione della valuta di visualizzazione (EURUSD, GBPUSD, USDCHF, USDJPY, AUDUSD, USDCAD, NZDUSD) viaggiano nella stessa richiesta.
|
||||
- Quote di mercato (`/api/v2/market-data/rates`) in batch fino a 1000 strumenti per chiamata: un polling ogni 3 s costa 20 richieste/min sulla quota condivisa di 120/min. Le coppie di conversione della valuta di visualizzazione (EURUSD, GBPUSD, USDCHF, USDJPY, AUDUSD, USDCAD, NZDUSD) viaggiano nella stessa richiesta.
|
||||
- Quota ordini: 20 richieste/min (demo e reale separate). Un basket costa 2 aperture + 2 chiusure.
|
||||
- Le quote di `rates` sono senza markup; il costo effettivo (markup + spread di mercato + overnight) arriva da `POST /trading/info/{demo/}costs` (20/min dedicate). Il cost gate somma i due.
|
||||
- Ordini: `POST /api/v2/trading/execution/{demo/}orders` (asincrono: esito con `orders:lookup?orderId=`; il server **non** registra l'`x-request-id` come `referenceId`, verificato il 2026-09-23); `sellShort` e leva > 1 richiedono `stopLossRate`. Il server può **ridurre** un ordine invece di rifiutarlo (2 000 USD di margine a margine esaurito, 2026-09-16): le unità eseguite si leggono dalla risposta, mai date per scontate. Chiusura: `POST /api/v1/trading/execution/{demo/}market-close-orders/positions/{id}`. Cancellazione: `DELETE /api/v2/trading/execution/{demo/}orders/{id}`.
|
||||
- Ordini: `POST /api/v2/trading/execution/{demo/}orders` (asincrono: esito con `orders:lookup?orderId=`; il server **non** registra l'`x-request-id` come `referenceId`, verificato il 2026-09-23); `sellShort` e leva > 1 richiedono `stopLossRate`. Il server può **ridurre** un ordine invece di rifiutarlo (2 000 USD di margine a margine esaurito, 2026-09-16): le unità eseguite si leggono dalla risposta, mai date per scontate. Chiusura: `POST /api/v1/trading/execution/{demo/}market-close-orders/positions/{id}`; la sua risposta non ha il profitto (`proceeds` = margine + profitto): il realizzato si legge dallo storico per `positionId` (`docs/DATA_SOURCES.md` §1.1). Cancellazione: `DELETE /api/v2/trading/execution/{demo/}orders/{id}`.
|
||||
- Esposizione minima per posizione: 1000 USD (`minPositionExposure`); leva ammessa 1-30 (majors) e 1-20 (minors). Il conto reale dell'utente vale 224,90 USD: con i limiti di rischio della strategia il reale non è praticabile oggi (vedi QUESTIONS D-05).
|
||||
@@ -1,6 +1,6 @@
|
||||
# Fonti dei dati
|
||||
|
||||
Aggiornato: 2026-09-16. Ogni fonte è stata verificata alla data indicata; se un feed cambia o sparisce, la voce va aggiornata e la decisione annotata in `docs/QUESTIONS.md`.
|
||||
Aggiornato: 2026-10-01 (5.1: rotte di chiusura e storico delle posizioni chiuse come P&L di record, §1.1; feed scaricati in background, §2-3; segreti e file di stato per conto, §4). Ogni fonte è stata verificata alla data indicata; se un feed cambia o sparisce, la voce va aggiornata e la decisione annotata in `docs/QUESTIONS.md`.
|
||||
|
||||
## 1. Mercato
|
||||
|
||||
@@ -25,7 +25,9 @@ Qualità (`data/market/data_quality.csv`, generato da `backtest ticks`, e `repor
|
||||
| `GET api/v1/trading/info/{demo/}orders/{orderId}` | ripiego per `orderId` con la risposta v1 (`statusID`, `errorCode`, `positions[] {positionID, rate, units, occurred, isOpen}`) | verificato con l'ordine 381739181. |
|
||||
| `DELETE api/v2/trading/execution/{demo/}orders/{orderId}` | cancellazione di un ordine non ancora eseguito (kill-switch) | 200 = richiesta accettata, non annullamento avvenuto: confermare con il lookup (7 o 9 = annullato, 6 = in corso). Idempotente su ordini già chiusi. |
|
||||
| `GET api/v1/trading/info/{demo/}pnl` | conto e posizioni in una chiamata: `clientPortfolio.credit`, `bonusCredit`, `unrealizedPnL`, `positions[] {positionID, instrumentID, isBuy, units, openRate, openDateTime, amount (margine), leverage, unrealizedPnL.pnL, totalFees}` | `equity = credit + bonus + Σ amount + unrealized`; `available = credit + bonus`; `usedMargin = Σ amount`. Il conto demo **non compare** in `api/v1/balances` (solo i conti reali). |
|
||||
| `GET api/v1/trading/info/trade/{demo/}history?minDate=…&page=…&pageSize=200` | posizioni chiuse: `positionId`, `orderId`, `openRate`, `closeRate`, `openTime`, `closeTime`, `netProfit`, `fees`, `investment` | `netProfit` **non** include `fees`. Fonte del realizzato della scheda Storico e della distinzione fra chiusure e movimenti di cassa. |
|
||||
| `POST api/v1/trading/execution/{demo/}market-close-orders/positions/{positionId}` | chiusura di una posizione (corpo `{"InstrumentID": …}`) | risponde con `orderForClose.orderID`: l'esito si legge sulla rotta seguente. Quota 20/min condivisa con gli ordini. |
|
||||
| `GET api/v1/trading/info/{demo/}close-orders/{orderId}` | esito della chiusura: `statusID`, `errorCode`, `proceeds`, `positions[] {positionID, occurred, rate, units, conversionRate, amount}` | schema verificato il 2026-09-30 (API v1.383.0). **Non ha alcun campo di profitto.** `proceeds` è, per la specifica, il totale restituito dalla chiusura sulle posizioni coinvolte: margine liberato più profitto (una posizione con `amount` 7 210,02 chiusa a +32,00 restituisce 7 242,02). I numeri della 5.0.0 lo confermano: «P&L oggi» di circa 47 000 USD su 139 000 di equity, in linea con la somma di investimento + profitto delle chiusure del giorno. **Non è mai il P&L**. Dalla 4.0.0 alla 5.0.0 il bot lo registrava come realizzato (vedi `docs/LEDGER_SCHEMA.md`, correzioni `pnl_realizzato`); dalla 5.1 resta solo come diagnostica (`CloseOutcome.Proceeds`). `rate` e `conversionRate` (valuta quotata → USD, 1 per le coppie in USD) servono alla **stima provvisoria**: `unità × Δprezzo × conversionRate − fee`, che coincide al centesimo con lo storico su NZDUSD, EURNZD e USDCAD. L'`orderId` della chiusura non è quello dello storico. Quota Lookup (60/min). |
|
||||
| `GET api/v1/trading/info/trade/{demo/}history?minDate=…&page=…&pageSize=200` | posizioni chiuse: `positionId`, `orderId`, `instrumentId`, `isBuy`, `units`, `openRate`, `closeRate`, `openTimestamp`, `closeTimestamp`, `netProfit`, `fees`, `investment` | **Il P&L di record** di ogni posizione chiusa (dalla 5.1): `netProfit − fees`. `netProfit` **non** include `fees` (nello storico demo del 2026-09 le fee sono sempre 0). `minDate` filtra sull'**ora di chiusura** a partire dalla mezzanotte UTC di quel giorno (verificato il 2026-09-30: `minDate=2026-09-29` comprende le posizioni aperte il 28 e chiuse il 29, esclude quelle chiuse il 28 alle 22:45 UTC); le righe arrivano dalla più recente; lo sguardo all'indietro dev'essere inferiore a un anno. L'`orderId` è l'ordine di **apertura** (`orders/{id}` risponde 200, `close-orders/{id}` 404): lo storico si unisce ai file del bot **per `positionId`**. Quota Default (60/min, budget locale 55): il motore lo legge circa ogni 5 minuti, ogni 5 s nel minuto dopo una chiusura e ogni 30 s finché una chiusura attende. Una pagina che non si legge è un **errore** (`BrokerException`), mai una lista vuota. Fonte del realizzato della scheda Storico, di «P&L oggi», delle righe di `baskets.csv` e della distinzione fra chiusure e movimenti di cassa. |
|
||||
|
||||
**Stati dell'ordine** (`status.id` / `statusID`): 1 Received, 2 Placed, 3 Filled, 4 Rejected, 5 PartiallyFilled, 6 PendingCancel, 7 Canceled, 8 Expired, 9 CanceledPartiallyFilled, 10 RejectedPartiallyFilled, 11 WaitingForMarket, 12 PendingTriggeredRate. Il bot tratta 3 e 5 come eseguito, 4, 7, 8, 9, 10 come rifiutato/annullato, 1, 2, 6, 11, 12 come in corso; in assenza di risposta lo stato è `Unknown` e l'ordine resta nel registro. Esiste anche `POST api/v3/trading/execution/{demo/}orders` (202, stessa semantica, `settlementType` obbligatorio): non usato, annotato per il futuro.
|
||||
|
||||
@@ -34,6 +36,8 @@ Qualità (`data/market/data_quality.csv`, generato da `backtest ticks`, e `repor
|
||||
| Fonte | URL | Formato | Aggiornamento | Note |
|
||||
|---|---|---|---|---|
|
||||
| Forex Factory via FairEconomy | `https://nfs.faireconomy.media/ff_calendar_thisweek.json` | JSON `[{title,country,date,impact,forecast,previous,actual}]`, `date` con offset (ora di New York) | il feed cambia più volte al giorno; il bot lo rilegge ogni 10 minuti, mai più di una richiesta al minuto | `country` è già il codice valuta (`USD, EUR, GBP, JPY, AUD, NZD, CAD, CHF, CNY`, `All`); `impact` ∈ {High, Medium, Low, Holiday} |
|
||||
|
||||
**Come si scaricano (dalla 5.1).** Calendario e notizie appartengono al processo, non al motore: un solo `FeedContextProvider` li scarica **in background** ogni 10 minuti (`ContextRefresher`, mai dentro il ciclo di decisione: fino alla 5.0 il ciclo aspettava tredici fonti una dopo l'altra, e dopo un'interruzione di rete quotazioni e uscite potevano aspettare minuti) e pubblica una fotografia immutabile; il sentiment, che decade nel tempo, si ricalcola circa una volta al minuto. Il processo li tiene aggiornati **anche a motore fermo**, così la pagina Mercato resta viva. Per ogni fonte la pagina Sistema (`/api/system` → `feeds`) mostra ultima richiesta, ultimo successo, errori di fila, attesa crescente in corso, verdetto di `robots.txt` e ultimo errore; nel tick, `health.feeds` vale `stale` quando il calendario non arriva da tre ore o nessuna fonte di notizie da due, `error` quando tutte le fonti falliscono.
|
||||
| variante XML | `https://nfs.faireconomy.media/ff_calendar_thisweek.xml` | `<weeklyevents><event>` con `date` MM-DD-YYYY e `time` 8:15am **in UTC** (verificato contro il JSON: "10:30pm" del 09-13 = "18:30-04:00") | idem | usata solo come riserva |
|
||||
|
||||
Archivio: `data/calendar/events.jsonl` (append-only, una riga per evento, dedup per `title+date+country`; un `actual` che arriva dopo la pubblicazione è una riga nuova). Feature derivate per ogni valuta: `minutesToNextHigh`, `minutesSinceLastHigh`, `surpriseLast = (actual − forecast)/|forecast|`.
|
||||
@@ -68,14 +72,22 @@ Copie dei feed usate dai test: `tests/fixtures/` (scaricate il 2026-09-16).
|
||||
| Rotta | Uso | Note |
|
||||
|---|---|---|
|
||||
| `POST https://api.telegram.org/bot<token>/sendMessage` | notifiche e risposte, corpo `{chat_id, text, parse_mode: "HTML", disable_web_page_preview: true}` | limite 4096 caratteri per messaggio (il bot spezza sulle righe); un invio al secondo; su 429 il corpo porta `parameters.retry_after`; un 4xx (token, chat o markup sbagliati) non viene ritentato |
|
||||
| `GET https://api.telegram.org/bot<token>/getUpdates?offset=<n>&timeout=25&allowed_updates=["message"]` | comandi in ingresso, long polling da un solo task | solo i messaggi con `chat.id` uguale a `TELEGRAM_CHAT_ID` vengono eseguiti; gli altri sono ignorati e annotati nel log; `offset` avanza all'ultimo `update_id` + 1 |
|
||||
| `GET https://api.telegram.org/bot<token>/getUpdates?offset=<n>&timeout=25&allowed_updates=["message"]` | comandi in ingresso, long polling da un solo task | solo i messaggi con `chat.id` uguale a `notifications.telegram.chatId` vengono eseguiti; gli altri sono ignorati e annotati nel log; `offset` avanza all'ultimo `update_id` + 1 |
|
||||
| `GET https://api.telegram.org/bot<token>/getMe` | verifica del token quando si salva da Impostazioni (dalla 5.1) | risponde con il nome del bot, che la pagina mostra; un token rifiutato non viene salvato |
|
||||
|
||||
Il token non è mai in un file del repository: `TELEGRAM_BOT_TOKEN` nell'ambiente (o, a scelta dell'operatore, `botToken` in `encelado.local.json`).
|
||||
Dalla 5.1 il token del bot si inserisce da **Impostazioni ▸ Notifiche Telegram**, viene verificato con `getMe` e vive solo in `/config/secrets.enc`, cifrato con la password dell'interfaccia; la chat (`chatId`) si imposta nella stessa pagina. Il token non è mai in un file del repository, in `encelado.json` o nell'ambiente: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` e il `botToken` scritto a mano in `encelado.json` o in `encelado.local.json` di un'installazione 5.0 vengono importati una volta al primo avvio della 5.1 e poi ignorati (D-48). Il server campione (`--sample`) non apre mai un canale Telegram: un secondo poller sullo stesso bot ruberebbe i comandi a quello vero.
|
||||
|
||||
## 4. Schema dei file (nel container `/config` e `/data`; fuori dal container `Documenti\Encelado`)
|
||||
## 4. Schema dei file (nel container `/config` e `/data`; fuori dal container la sandbox `deploy/local/` o `Documenti\Encelado`)
|
||||
|
||||
```
|
||||
/config: encelado.json, strategy.json, instruments.json, etoro.keys.enc (chiavi cifrate), STOP (kill-switch da file)
|
||||
/config: encelado.json, strategy.json, instruments.json, STOP (kill-switch da file)
|
||||
secrets.enc chiavi eToro dei due conti e token Telegram, AES-256-GCM con la password dell'interfaccia (5.1)
|
||||
secrets.enc.<data>.bak il deposito messo da parte da «Ricomincia» (password cambiata e non sbloccata)
|
||||
secrets.key chiave locale casuale, solo senza password (sviluppo); sparisce quando la password compare
|
||||
session.key segreto del server nel cookie di sessione (32 byte casuali, creato al primo avvio con una password); cancellarlo chiude le sessioni
|
||||
import-5.1.json cosa ha importato una volta l'avvio della 5.1 dalle variabili e dai file della 5.0, e su che conto operava la 5.0 (legacyState)
|
||||
etoro.keys.enc.migrato il file di chiavi della 5.0, dopo l'importazione (non più letto)
|
||||
encelado.json.<data>.bak backup di «Ripristina encelado.json di fabbrica»
|
||||
/data:
|
||||
data/market/candles_<SYMBOL>_M15.csv timeUtc;bidOpen;bidHigh;bidLow;bidClose;askOpen;askHigh;askLow;askClose;spreadMean;ticks;motivazione
|
||||
data/market/data_quality.csv simbolo;tick_letti;tick_scartati;barre;prima_barra;ultima_barra;buchi_feriali_oltre_1h;barre_spike;spread_mediano_pip;motivazione
|
||||
@@ -85,12 +97,13 @@ data/cache/<fonte>.xml|json ultimo corpo buono di ogni feed
|
||||
data/ledger/decisions.jsonl vedi docs/LEDGER_SCHEMA.md (rotazione mensile in decisions_YYYYMM.jsonl)
|
||||
data/ledger/baskets.csv vedi docs/LEDGER_SCHEMA.md
|
||||
data/ledger/orders.jsonl una riga per ordine inviato e per cambio di stato (5.0)
|
||||
data/state/baskets_state.json posizioni aperte, ingressi in attesa, picco di equity al netto dei movimenti di cassa, blocchi
|
||||
data/state/pending_orders.json il registro degli ordini (5.0)
|
||||
data/state/heartbeat.json ultimo battito (30 s), run, nota di arresto (5.0)
|
||||
data/state/instance.lock un solo bot per cartella dati (5.0)
|
||||
data/state/paper_state.json il conto del simulatore (solo Paper)
|
||||
data/models/*.json modelli (livelli 1-3) e stato del bandit
|
||||
data/state/baskets_state.demo.json stato del motore del conto demo: basket aperti, ingressi in attesa, chiusure in attesa del P&L,
|
||||
picco al netto dei movimenti di cassa, blocchi, residuo, pausa, giornata della perdita giornaliera (5.1)
|
||||
data/state/baskets_state.live.json lo stesso per il conto reale (5.1); il file unico baskets_state.json della 5.0 resta come .migrato
|
||||
data/state/pending_orders.json il registro degli ordini (5.0), uno per i due conti: ogni ordine porta il suo mode (5.1)
|
||||
data/state/heartbeat.json ultimo battito (recovery.heartbeatSeconds, 30 s), run, nota di arresto (5.0)
|
||||
data/state/instance.lock un solo scrittore per cartella dati: motore, ciclo di apprendimento a motore fermo, backtest learn
|
||||
data/models/*.json modelli (livelli 1-3), stato del bandit, last_cycle.json, learning_state.json (vedi LEDGER_SCHEMA)
|
||||
knowledge/*.csv, *.md calibrazione, proposte, registri, insight settimanali
|
||||
reports/*.csv qualità dati, falsificazione, bonifica_YYYYMMDD, recupero_<run_id> (5.0)
|
||||
logs/encelado.log log applicativo (;)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Encelado in Docker
|
||||
|
||||
Aggiornato: 2026-09-23 (5.0). Dalla 5.0 il bot gira **solo** nel container (ADR-0007, ADR-0008): un processo `Encelado.Server` che ospita il motore e serve l'interfaccia web su Kestrel. Per Unraid c'è il template in `deploy/unraid/` (vedi il README lì).
|
||||
Aggiornato: 2026-10-01 (5.1). Il bot gira **solo** nel container (ADR-0007, ADR-0008): un processo `Encelado.Server` che ospita il motore e serve l'interfaccia web su Kestrel. Dalla 5.1 il container ha **una sola variabile**, la password dell'interfaccia: tutto il resto si imposta dalla pagina (ADR-0010). Per Unraid c'è il template in `deploy/unraid/` (vedi il README lì, anche per l'aggiornamento da un container 5.0).
|
||||
|
||||
## Immagine
|
||||
|
||||
@@ -11,57 +11,55 @@ dotnet msbuild build/Release.proj -t:Docker # :<versione dal tag> e :
|
||||
docker build -t encelado:dev --build-arg GIT_COMMIT=$(git rev-parse --short=12 HEAD) . # a mano
|
||||
```
|
||||
|
||||
Stadi: `build` (restore + compilazione Release), `test` (la suite xunit: se è rossa l'immagine non esiste), `publish` (framework-dependent, non trimmed), `runtime` (`mcr.microsoft.com/dotnet/aspnet:10.0` + `gosu` + `tzdata`). L'immagine porta le etichette OCI `version` e `revision`; commit e data di build sono in Impostazioni ▸ Informazioni.
|
||||
Stadi: `build` (restore + compilazione Release), `test` (la suite xunit: se è rossa l'immagine non esiste), `publish` (framework-dependent, non trimmed), `runtime` (`mcr.microsoft.com/dotnet/aspnet:10.0` + `gosu` + `tzdata`). L'immagine porta le etichette OCI `version` e `revision`; commit e data di build sono in Sistema ▸ Informazioni.
|
||||
|
||||
## Volumi
|
||||
|
||||
| Dentro | Contenuto | Su Unraid |
|
||||
|---|---|---|
|
||||
| `/config` | `encelado.json`, `strategy.json`, `instruments.json`, `etoro.keys.enc` (chiavi cifrate), file `STOP` per il kill-switch | `/mnt/user/appdata/encelado/config` |
|
||||
| `/data` | `data/` (ledger, stato, barre, cache, modelli), `knowledge/`, `reports/`, `results/`, `logs/` | `/mnt/user/appdata/encelado/data` |
|
||||
| `/config` | `encelado.json`, `strategy.json`, `instruments.json`, `secrets.enc` (chiavi eToro dei due conti e token Telegram, cifrati con la password), `import-5.1.json` (cosa è stato importato da un container 5.0), `session.key` (il segreto del server nel cookie di sessione), file `STOP` per il kill-switch | `/mnt/user/appdata/encelado/config` |
|
||||
| `/data` | `data/` (ledger, stato per conto, registro degli ordini, barre, cache, modelli), `knowledge/`, `reports/`, `results/`, `logs/` | `/mnt/user/appdata/encelado/data` |
|
||||
|
||||
Al primo avvio il container semina `encelado.json` e `strategy.json` dai valori di fabbrica. Nel container `run.dataPath`, `knowledgePath`, `reportsPath` e `logging.path` vengono rimappati sotto `/data` qualunque cosa dica il file: non c'è niente da cambiare a mano. I file appartengono a `PUID:PGID`.
|
||||
Al primo avvio il container semina `encelado.json` e `strategy.json` dai valori di fabbrica. Nel container `run.dataPath`, `knowledgePath`, `reportsPath` e `logging.path` vengono rimappati sotto `/data` qualunque cosa dica il file: non c'è niente da cambiare a mano. I file appartengono a `PUID:PGID` (99:100 di fabbrica, `nobody:users` di Unraid).
|
||||
|
||||
## Variabili d'ambiente
|
||||
|
||||
| Variabile | Default | Effetto |
|
||||
|---|---|---|
|
||||
| `ENCELADO_WEB_TOKEN` | vuoto | Token dell'interfaccia. **Senza token il server ascolta solo su localhost del container**: dalla rete non si vede niente. Si inserisce una volta nel browser e resta in un cookie HttpOnly per 30 giorni; l'API accetta anche `Authorization: Bearer <token>`. |
|
||||
| `ENCELADO_WEB_PORT` | `8080` | Porta di Kestrel. |
|
||||
| `ETORO_API_KEY`, `ETORO_USER_KEY` | vuoto | Chiavi eToro Public API; hanno la precedenza sul file cifrato. |
|
||||
| `ENCELADO_KEY_PASSPHRASE` | vuoto | Passphrase del file `etoro.keys.enc` (AES-256-GCM, PBKDF2 200 000 iterazioni) scritto da Impostazioni ▸ Chiavi eToro. Senza passphrase il salvataggio dall'interfaccia è disattivato. |
|
||||
| `ETORO_ENVIRONMENT` | `demo` | `demo` o `real`. |
|
||||
| `ENCELADO_EXECUTION_MODE` | `Demo` | `Paper`, `Demo`, `Live`. |
|
||||
| `ENCELADO_CONFIRM_LIVE` | vuoto | La frase `CONFERMO LIVE`, obbligatoria per `Live` insieme a `run.allowLive = true`. |
|
||||
| `ENCELADO_AUTOSTART` | `1` | `0` = il motore non parte da solo: si preme AVVIA nell'interfaccia. |
|
||||
| `ENCELADO_DISPLAY_CURRENCY` | `USD` | Valuta di visualizzazione (USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD). Il ledger resta in USD. |
|
||||
| `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | vuoto | Notifiche e comandi Telegram. |
|
||||
| `TZ` | `UTC` | Fuso degli orari a schermo e nel log (nome IANA, es. `Europe/Rome`); il ledger è UTC. Vale anche come `ui.timeZone` se il file dice `computer`. |
|
||||
| `PUID`, `PGID` | `99`, `100` | Utente e gruppo del processo e dei volumi (`nobody:users` di Unraid). |
|
||||
| `ENCELADO_LOG_LEVEL`, `ENCELADO_CONFIG_DIR`, `ENCELADO_DATA_DIR` | — | Livello di log; cartelle alternative (di norma non servono nel container). |
|
||||
| `ENCELADO_PASSWORD` | vuoto | **L'unica da impostare**: la password dell'interfaccia («Password interfaccia» nel template, mascherata e obbligatoria). Si scrive una volta nella pagina di accesso e resta in un cookie HttpOnly per 30 giorni (un HMAC della password e di un segreto del server in `/config/session.key`, mai la password); l'API accetta anche `Authorization: Bearer <password>`. **Cifra anche i segreti** salvati da Impostazioni: cambiarla li blocca finché non li sblocchi con quella precedente (o ricominci). **Senza password il server ascolta solo su localhost del container**: dalla rete non si vede niente. `ENCELADO_WEB_TOKEN`, il nome della 5.0, vale ancora come alias deprecato (con un avviso; se sono diverse vince `ENCELADO_PASSWORD`). |
|
||||
|
||||
Conto (demo o reale), chiavi eToro dei due conti, Telegram (token, chat, notifiche, comandi), valuta di visualizzazione, livello e rotazione del log, avvio automatico, chiusura all'arresto, strategia: **tutto in Impostazioni**, applicato subito dal bot quando può.
|
||||
|
||||
Le altre variabili che il processo legge sono **interne all'immagine** o servono allo sviluppo, e non vanno toccate: `ENCELADO_IN_CONTAINER=1` (il rilevamento del container), `ENCELADO_WEB_PORT=8080` (la porta di Kestrel dentro il container: per un'altra porta si cambia la mappatura), `TZ=UTC`, `PUID=99`, `PGID=100` (l'entrypoint; su Unraid `TZ` lo aggiunge Unraid da sé), `ENCELADO_CONFIG_DIR` e `ENCELADO_DATA_DIR` (cartelle alternative, usate da F5 e dagli script sulla sandbox). `TZ` vale **solo per la visualizzazione**: gli orari scritti dal server (riga di stato) e l'offset del log; gli orologi della pagina usano il fuso del browser e il ledger è sempre UTC.
|
||||
|
||||
**Variabili della 5.0** (`ETORO_API_KEY`, `ETORO_USER_KEY`, `ETORO_ENVIRONMENT`, `ENCELADO_EXECUTION_MODE`, `ENCELADO_KEY_PASSPHRASE`, `ENCELADO_CONFIRM_LIVE`, `ENCELADO_AUTOSTART`, `ENCELADO_DISPLAY_CURRENCY`, `ENCELADO_LOG_LEVEL`, `ENCELADO_TIME_ZONE`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`): al **primo avvio della 5.1** vengono importate una volta (le chiavi e il token nel deposito cifrato, solo dove è vuoto; la chat e le impostazioni in `encelado.json`, le impostazioni solo se diverse dal valore di fabbrica e il file è ancora di fabbrica; il vecchio `etoro.keys.enc` con la sua passphrase, poi rinominato `.migrato`). `TZ` e `ENCELADO_CONFIRM_LIVE` non vengono mai importate. Da lì in poi ogni variabile rimasta è **ignorata** ed elencata nel log, nella striscia degli allarmi e in Sistema ▸ Segreti: si possono togliere dal container. Il file `/config/import-5.1.json` ricorda cosa è stato fatto e impedisce di ripeterlo: per cambiare le chiavi più avanti (chiavi rigenerate sul portale) non si tocca il container, si reinseriscono in Impostazioni ▸ Conto; una `ETORO_API_KEY` cambiata nel container verrebbe ignorata e il bot resterebbe con le chiavi vecchie.
|
||||
|
||||
## Avvio, arresto, aggiornamento
|
||||
|
||||
```powershell
|
||||
docker compose up -d # sviluppo locale: cartelle in deploy/local/, segreti in .env
|
||||
docker compose up -d # sviluppo locale: cartelle in deploy/local/, password "sviluppo" (o ENCELADO_PASSWORD in .env)
|
||||
docker compose logs -f encelado
|
||||
docker compose down # SIGTERM → arresto pulito (45 s di grazia)
|
||||
docker pull 192.168.30.23:3000/alby96/encelado:latest && docker compose up -d # aggiornamento
|
||||
```
|
||||
|
||||
Su `SIGTERM` il server ferma il motore come da `run.closeOnShutdown` (default `false`: i basket restano sul conto con gli stop nativi), chiude il ledger, scrive l'heartbeat con la nota di arresto ed esce con 0. Al riavvio riprende lo stato salvato, riconcilia il conto e, se è passato più di `recovery.thresholdMinutes`, esegue il recupero dopo inattività (`docs/RUNBOOK.md`).
|
||||
Su `SIGTERM` il server ferma il motore come da `run.closeOnShutdown` (default `false`: i basket restano sul conto con gli stop nativi; `true`: il motore stesso, sul suo thread, blocca le nuove entrate e chiude tutto entro 30 s), dà a un kill-switch in corso 30 s per finire (poi lo interrompe e registra il residuo, Halted-Residuo), chiude il ledger, scrive l'heartbeat con la nota di arresto ed esce con 0. I 45 s di grazia del container (`--stop-timeout 45` nel template, `stop_grace_period` nella compose) coprono questi tempi. Al riavvio riprende lo stato del conto, riconcilia il conto e, se è passato più di `recovery.thresholdMinutes`, esegue il recupero dopo inattività (`docs/RUNBOOK.md`). In modalità **Live** il motore non riparte da solo: resta fermo fino ad AVVIA con la frase `CONFERMO LIVE`, e Telegram lo dice.
|
||||
|
||||
## Healthcheck
|
||||
|
||||
`HEALTHCHECK` ogni 30 s: `dotnet /app/Encelado.Server.dll --health` chiama `GET /api/health` sulla porta configurata ed esce 0 solo se il server risponde, il disco dei dati è scrivibile e, a motore acceso, l'heartbeat è più fresco di 105 s. `docker inspect --format '{{.State.Health.Status}}' encelado` per leggerlo. Il campo JSON di `/api/health` dice quale condizione fallisce.
|
||||
`HEALTHCHECK` ogni 30 s: `dotnet /app/Encelado.Server.dll --health` chiama `GET /api/health` sulla porta configurata ed esce 0 solo se il server risponde, il disco dei dati è scrivibile e, a motore acceso, l'heartbeat è più fresco di 3 × `recovery.heartbeatSeconds` + 15 s (105 s con il default di 30 s; l'intervallo si cambia a caldo in Impostazioni ▸ Strategia). `docker inspect --format '{{.State.Health.Status}}' encelado` per leggerlo. Il campo JSON di `/api/health` dice quale condizione fallisce. L'heartbeat si scrive all'inizio di ogni giro del motore: un kill-switch o una chiusura che durano minuti possono far risultare il container non sano per quel tempo.
|
||||
|
||||
## Log
|
||||
|
||||
Sulla console (stdout, `docker logs`) **e** nel file `/data/logs/encelado.log` (CSV `;`, rotazione per dimensione). L'ora nel log è nel fuso `TZ` con l'offset esplicito; il ledger resta UTC. Il livello si cambia con `ENCELADO_LOG_LEVEL` o da Impostazioni.
|
||||
Sulla console (stdout, `docker logs`) **e** nel file `/data/logs/encelado.log` (CSV `;`, rotazione per dimensione). L'ora nel log è nel fuso `TZ` con l'offset esplicito; il ledger resta UTC. Livello, dimensione e numero dei file si cambiano da Impostazioni ▸ Log, con effetto immediato.
|
||||
|
||||
## Rete
|
||||
|
||||
Il server ascolta su tutte le interfacce **solo** quando `ENCELADO_WEB_TOKEN` è impostato. Non c'è TLS: l'interfaccia è pensata per la rete locale (Unraid) o dietro un reverse proxy che lo aggiunge. Le rotte `/api/health`, `/login`, `/icon.svg` e `/manifest.webmanifest` sono libere; tutto il resto chiede il token.
|
||||
Il server ascolta su tutte le interfacce **solo** con `ENCELADO_PASSWORD` impostata **e** nel container (fuori dal container, cioè con F5 o `run-dev`, solo con l'argomento `--listen-all`); altrimenti solo su localhost. Non c'è TLS: l'interfaccia è pensata per la rete locale (Unraid) o dietro un reverse proxy che lo aggiunge. Le rotte `/login`, `/logout`, `/api/health`, `/css/*`, `/img/*`, `/icon.svg` e `/manifest.webmanifest` sono libere; tutto il resto chiede la password.
|
||||
|
||||
Protezioni (ADR-0010): ogni POST o DELETE sotto `/api/` deve avere `Content-Type: application/json` (415 altrimenti) e venire dalla stessa origine (`Origin` e `Sec-Fetch-Site`: 403 altrimenti), così una pagina di un altro sito non può comandare il bot; senza password il server risponde 403 a ogni `Host` che non sia `localhost`, `127.0.0.1` o `[::1]`. Dopo una password errata l'indirizzo che l'ha mandata aspetta 1, 2, 4… fino a 30 s (429).
|
||||
|
||||
**Dietro un reverse proxy** il proxy deve passare l'header `Host` originale oppure `X-Forwarded-Host`, altrimenti l'`Origin` del browser non torna con l'`Host` che arriva al bot e **ogni salvataggio e ogni comando riceve 403**. Nginx Proxy Manager, SWAG, Caddy e Traefik lo fanno di fabbrica; un `nginx` scritto a mano vuole `proxy_set_header Host $host;`. Il proxy fa sembrare tutti i client un solo indirizzo: l'attesa dopo una password errata vale per tutti quelli che passano da lui.
|
||||
|
||||
## Registro privato in HTTP
|
||||
|
||||
@@ -76,7 +74,7 @@ Due workflow in `.gitea/workflows/`, sul modello di Rea:
|
||||
| `ci.yml` | push su `main`, pull request | `dotnet build -warnaserror` e `dotnet test`; poi `docker build` dell'immagine (senza pubblicarla) per accorgersi di una Dockerfile rotta |
|
||||
| `release.yml` | tag `v*` | costruisce e pubblica `<host>/alby96/encelado:<versione>` e `:latest` sul registro di Gitea (solo `linux/amd64`: la build esegue i test e sotto QEMU sarebbe lentissima), poi crea la release con il template Unraid allegato; se la release esiste già (creata dalla catena) aggiunge solo l'allegato mancante |
|
||||
|
||||
Servono due cose che al 2026-09-23 **mancano**:
|
||||
Servono due cose che al 2026-10-01 **mancano ancora**:
|
||||
|
||||
1. **Un runner.** Sul server non ce n'è nessuno (`/api/v1/repos/Alby96/Encelado/actions/runners` è vuoto): i workflow restano in coda. Il modo più semplice è un container `gitea/act_runner` su Unraid con il socket di Docker montato (`/var/run/docker.sock`), registrato con il token di *Site Administration ▸ Actions ▸ Runners ▸ Create new runner* e con l'etichetta `ubuntu-latest:docker://catthehacker/ubuntu:act-latest`. Con il registro in HTTP il runner (e la sua immagine di lavoro) deve avere `192.168.30.23:3000` fra gli `insecure-registries`.
|
||||
2. **Il segreto `REGISTRY_TOKEN`** nel repository (*Impostazioni ▸ Actions ▸ Segreti*): un token dell'utente con `package:write` e `repository:write` (lo stesso di `build/gitea.json` va bene).
|
||||
@@ -89,10 +87,10 @@ Finché il runner non c'è, il rilascio si fa dal PC con `dotnet msbuild build/R
|
||||
|
||||
| Modo | Comando | Note |
|
||||
|---|---|---|
|
||||
| F5 in VS Code | `Encelado (server)` | processo locale, `ENCELADO_CONFIG_DIR`/`ENCELADO_DATA_DIR` puntati alla sandbox, browser aperto da solo, motore fermo finché non premi AVVIA (senza token: solo localhost, nessun login) |
|
||||
| script | `scripts\run-dev.ps1` / `sh scripts/run-dev.sh` (`--sample`, `--autostart`) | come F5 ma da terminale, con i comandi da tastiera |
|
||||
| container | `scripts\run-docker.ps1` / `sh scripts/run-docker.sh` / `docker compose up -d --build` | l'immagine vera; token `sviluppo` salvo `ENCELADO_WEB_TOKEN` in `.env`; `--down` ferma con SIGTERM |
|
||||
| F5 in VS Code | `Encelado (server)` | processo locale, `ENCELADO_CONFIG_DIR`/`ENCELADO_DATA_DIR` puntati alla sandbox, password `sviluppo` (per i segreti della sandbox), **solo localhost** (per la rete serve `--listen-all`), browser aperto da solo, motore fermo finché non premi AVVIA |
|
||||
| script | `scripts\run-dev.ps1` / `sh scripts/run-dev.sh` (`-Sample`/`--sample`, `-Autostart`/`--autostart`, `-Port`) | come F5 ma da terminale, con i comandi da tastiera |
|
||||
| container | `scripts\run-docker.ps1` / `sh scripts/run-docker.sh` / `docker compose up -d --build` | l'immagine vera; password `sviluppo` salvo `ENCELADO_PASSWORD` in `.env` (lo script dice da dove viene, mai il valore); `-Down` / `--down` ferma con SIGTERM |
|
||||
|
||||
`ENCELADO_DATA_DIR` vale anche fuori dal container: separa i dati dalla configurazione come fa `/data`. Le chiavi salvate da Impostazioni finiscono in `deploy/local/config/etoro.keys.enc` e valgono per F5 e per il container (stessa `ENCELADO_KEY_PASSPHRASE`). `Encelado (campione)` e `--sample` servono lo snapshot finto: nessuna chiave, per lavorare sulle pagine e fotografarle (`scripts\screenshots.ps1`).
|
||||
Tutti e tre usano la stessa password `sviluppo`, così i segreti cifrati salvati da Impostazioni (chiavi eToro, token Telegram) in `deploy/local/config/secrets.enc` valgono per F5, per gli script e per il container. `ENCELADO_DATA_DIR` vale anche fuori dal container: separa i dati dalla configurazione come fa `/data`. `Encelado (campione)`, `run-dev -Sample` e `--sample` servono dati d'esempio **in cartelle temporanee** (`%TEMP%/encelado-campione-…`, cancellate all'uscita): non leggono né scrivono la sandbox, i segreti o Telegram, e ogni comando o salvataggio risponde «modalità dimostrativa». Servono a lavorare sulle pagine e a fotografarle (`scripts\screenshots.ps1`).
|
||||
|
||||
Fuori dalla sandbox, senza variabili, il processo locale usa `Documenti\Encelado`: sconsigliato, è la cartella dell'installazione 4.0.0.
|
||||
@@ -8,44 +8,63 @@
|
||||
| **z-score** | `(X − media_W) / σ_W` del cross sintetico su una finestra di W barre M15. Ingresso a `|z| ≥ z_in`, uscita a `|z| ≤ z_out` o allo stop `|z| ≥ z_stop`. |
|
||||
| **ρ_W, ρ_20** | Correlazione rolling dei rendimenti delle due gambe su W e su 20 barre. Attesa negativa per i basket della specifica (`rho_min` −0,6). |
|
||||
| **Half-life (HL)** | Semiperiodo di mean reversion del cross, in barre, da un OLS di Δx su x(t−1). Ammesso fra `halfLifeMinBars` e `halfLifeMaxBars`. |
|
||||
| **Preset** | Conservative / Moderate / Aggressive: z_in, rischio per basket, numero massimo di basket, TP in pip, aggiunte, z_stop. |
|
||||
| **Preset** | Conservative / Moderate / Aggressive: z_in, rischio per basket, numero massimo di basket, TP in pip, aggiunte, z_stop. Dalla 5.1 è parte fissa della strategia (Impostazioni ▸ Strategia): un cambio vale per i basket nuovi, quelli aperti tengono i valori e il preset con cui sono entrati. |
|
||||
| **TP di basket** | Take-profit in pip, somma dei pip delle due gambe (come nell'interfaccia di riferimento). |
|
||||
| **Cost gate** | Il rifiuto di un ingresso se il TP non copre almeno `costMultiple` volte il costo stimato (spread reale + markup + commissioni + overnight atteso), o se lo spread è più del doppio della mediana delle ultime 24 ore. |
|
||||
| **Break-even** | Il costo in pip oltre il quale il P&L medio lordo di un basket diventa negativo: se è vicino a zero, il segnale non ha contenuto. |
|
||||
| **Vol-parity sizing** | Le unità di ogni gamba sono inversamente proporzionali alla sua volatilità (ATR), così le due gambe contribuiscono allo stesso rischio; il rischio totale è `riskPerBasketPct` dell'equity alla distanza dello stop. |
|
||||
| **Leg-risk** | Il rischio di restare con una sola gamba: se la seconda viene rifiutata, la prima viene chiusa subito (`leg_risk_unwind`); se la seconda è senza esito, il basket aspetta (`PendingB`) finché il registro degli ordini non sa. |
|
||||
| **Registro degli ordini** | `OrderTracker` e il file `data/state/pending_orders.json`: ogni ordine inviato, scritto prima della chiamata e seguito finché il server non dice eseguito, rifiutato o annullato, o finché la posizione non compare sul conto. |
|
||||
| **Registro degli ordini** | `OrderTracker` e il file `data/state/pending_orders.json`: ogni ordine inviato, scritto prima della chiamata e seguito finché il server non dice eseguito, rifiutato o annullato, o finché la posizione non compare sul conto. Un file per i due conti; ogni ordine porta il suo conto e un motore tocca solo i suoi. |
|
||||
| **PendingA / PendingB** | Stati del basket con una gamba senza esito: nessun nuovo ordine, valutazione sospesa, ripresa alla risoluzione. |
|
||||
| **Orfana-bot** | Una posizione sul conto aperta dal bot (registro o firma nel ledger) che non appartiene a nessun basket: adottata e chiusa. |
|
||||
| **Esterna** | Una posizione sul conto senza la firma del bot: segnalata, contata, mai toccata. |
|
||||
| **Esterna** | Una posizione sul conto senza la firma del bot: segnalata, contata, mai toccata (salvo dal kill-switch con la scelta esplicita o con `risk.closeForeignOnKill`). |
|
||||
| **Movimento di cassa** | Deposito, prelievo o accredito virtuale: un salto del saldo che nessuna chiusura spiega. Escluso dal P&L, dal picco e dal drawdown. |
|
||||
| **Bonifica** | La pulizia una tantum delle orfane con conferma per posizione (`--bonifica`). |
|
||||
| **Halted-Residuo** | Lo stato del motore dopo un kill-switch che non è riuscito ad appiattire le posizioni del bot: banner con l'elenco, reset rifiutato finché restano. |
|
||||
| **Proceeds** | Il campo della risposta di chiusura di eToro: il denaro restituito al conto, cioè margine liberato più profitto. **Non è il P&L**: dalla 4.0.0 alla 5.0.0 il bot lo registrava come tale (il «P&L oggi» di 47 000 USD su 139 000), corretto dalla 5.1 (ADR-0011). |
|
||||
| **Realizzato / P&L di record** | Il risultato di una posizione chiusa secondo lo storico di eToro: `netProfit − fees` della riga con lo stesso `positionId`. È la fonte della pagina Storico, di «P&L oggi», delle righe di `baskets.csv` e delle etichette. |
|
||||
| **Stima provvisoria** | Il risultato di una chiusura calcolato dalla risposta di chiusura (unità × differenza di prezzo × tasso di conversione − costi), usato finché lo storico non conferma; scritto come «P&L: stima» dopo 30 minuti, mai usato per addestrare. |
|
||||
| **Coda di regolamento** | `pendingSettlements` nello stato del conto: le chiusure che aspettano lo storico eToro per diventare righe di `baskets.csv`. Sopravvive ai riavvii. |
|
||||
| **P&L oggi** | Il realizzato netto delle posizioni del bot chiuse nella giornata UTC (più le stime non ancora confermate, segnate «stima»); uguale al periodo «oggi» dello Storico. Accanto: la variazione dell'equity netta da mezzanotte. |
|
||||
| **Correzione `pnl_realizzato`** | Una riga nuova di `decisions.jsonl` che dà il realizzato vero di una riga di `baskets.csv` scritta dalla 4.0.0-5.0.0; il lettore corretto la applica. Il ledger non si modifica mai. |
|
||||
| **Bonifica** | La pulizia una tantum delle orfane con conferma per posizione (`--bonifica`, pagina Posizioni). |
|
||||
| **Halted-Residuo** | Lo stato del motore dopo un kill-switch che non è riuscito ad appiattire le posizioni del bot (o interrotto dall'arresto del processo): allarme con l'elenco, reset rifiutato finché restano. |
|
||||
| **Verifica di piattezza** | La rilettura del conto dopo il kill-switch finché le posizioni del bot non sono sparite; niente è «chiuso» prima. |
|
||||
| **Margin guard** | Sotto equity / margine usato = 1,5 niente entrate; sotto 1,2 si chiude il basket con il P&L peggiore. |
|
||||
| **sizing_bound** | Quale vincolo ha deciso la size di un basket: `risk`, `margin`, `leverage`, `units`; `min_exposure` quando nessuna size è ammessa. |
|
||||
| **Heartbeat** | `data/state/heartbeat.json`, scritto ogni 30 s: misura l'inattività che fa scattare il recupero. |
|
||||
| **Heartbeat** | `data/state/heartbeat.json`, scritto ogni `recovery.heartbeatSeconds` (30 s): misura l'inattività che fa scattare il recupero; `/api/health` lo vuole più fresco di 3 intervalli + 15 s. |
|
||||
| **Recupero** | La procedura dopo un'inattività oltre la soglia: ordini pendenti, riconciliazione, barre perse, ogni basket aperto rivalutato (chiudi/tieni), rapporto, riscaldamento. |
|
||||
| **Lock di istanza** | `data/state/instance.lock`, tenuto in esclusiva: un solo bot per cartella dati. |
|
||||
| **Lock di istanza** | `data/state/instance.lock`, tenuto in esclusiva: un solo scrittore per cartella dati (il motore, la manutenzione dell'apprendimento a motore fermo, `backtest learn`). |
|
||||
| **Lucchetto del ciclo di vita** | Il lucchetto del supervisore che fa passare uno alla volta avvio, arresto, riavvio automatico, rilascio di un motore in errore e ciclo di apprendimento a motore fermo (ADR-0012). |
|
||||
| **Comando critico** | Kill-switch, chiusura di un basket, chiusura dei residui o chiusura della bonifica in coda o in corso: FERMA e i riavvii automatici non li interrompono (409), finché il motore li ha in mano, anche se chi li ha chiesti ha smesso di aspettare. |
|
||||
| **Equity stop** | Chiusura di tutto e blocco a un drawdown del 9 % dal picco; riparte solo con un reset motivato. |
|
||||
| **Kill-switch** | Chiusura immediata di tutto e blocco delle nuove entrate: pulsante, comando o file `STOP`. |
|
||||
| **Paper / Demo / Live** | Simulatore locale / conto demo eToro / conto reale. Il bot opera da solo in tutte e tre (D-20). |
|
||||
| **Ledger** | `decisions.jsonl` (ogni decisione con le sue feature) e `baskets.csv` (ogni basket chiuso). Append-only: le correzioni sono righe nuove. |
|
||||
| **Perdita giornaliera** | Il calo dell'equity netta dalla mezzanotte UTC oltre `dailyLossPct` (3 %): raggiunto una volta, niente nuove entrate né aggiunte fino alle 00:00 UTC anche se l'equity recupera (D-52); non chiude niente. |
|
||||
| **Kill-switch** | Chiusura immediata di tutte le posizioni del bot e blocco delle nuove entrate: pulsante KILL, `kill` da console, `/kill CONFERMO` da Telegram o file `STOP` in `/config`. |
|
||||
| **Demo / Live** | La modalità, che dalla 5.1 è anche il conto: Demo = conto demo eToro (ordini veri, denaro virtuale), Live = conto reale (`run.allowLive` e la frase `CONFERMO LIVE` a ogni avvio; non parte mai da solo). Il bot opera da solo in entrambe (D-20). `Paper` (simulatore locale) è stata eliminata nella 5.1. |
|
||||
| **Stato per conto** | `baskets_state.demo.json` e `baskets_state.live.json`: basket, blocchi, residui, pausa, picco, chiusure in attesa e giornata della perdita giornaliera di ciascun conto; un cambio di conto non tocca l'altro (D-53). |
|
||||
| **Ledger** | `decisions.jsonl` (ogni decisione con le sue feature), `baskets.csv` (ogni basket chiuso), `orders.jsonl` (ogni ordine). Append-only: le correzioni sono righe nuove. |
|
||||
| **Meta-modello** | La regressione logistica (livello 1) che stima la probabilità che un basket finisca in utile. In ombra finché non supera i cancelli di attivazione. |
|
||||
| **Challenger** | L'MLP (livello 2) valutato accanto al campione. |
|
||||
| **Bandit** | Il campionamento di Thompson (livello 3) che propone il preset per terzile di volatilità. |
|
||||
| **Challenger** | L'MLP (livello 2) valutato accanto al campione; addestrato solo con `learning.enabled` e `learning.challenger` accesi. |
|
||||
| **Bandit** | Il campionamento di Thompson (livello 3) che propone il preset per terzile di volatilità; premia il preset con cui il basket è entrato e non applica mai niente. |
|
||||
| **Ciclo di apprendimento** | Ricostruzione del dataset dal ledger, valutazione walk-forward, riaddestramento, base di conoscenza. Gira in background e il thread di decisione lo applica (ADR-0014); «Esegui ciclo» nella pagina Apprendimento, settimanale solo con `learning.weeklyCycle`. |
|
||||
| **Manutenzione a motore fermo** | «Esegui ciclo» con il motore fermo: il server prende il lock di istanza, addestra e applica; AVVIA risponde 409 finché dura. |
|
||||
| **Walk-forward** | Valutazione in cui ogni previsione usa solo dati precedenti; per la griglia del backtest: scegli il migliore dei 6 mesi passati, applicalo al mese successivo. |
|
||||
| **PSR / DSR** | Probabilistic e Deflated Sharpe Ratio: la probabilità che lo Sharpe osservato sia sopra zero, tenendo conto di asimmetria, curtosi, lunghezza e (DSR) del numero di configurazioni provate. |
|
||||
| **PBO** | Probabilità di overfitting del backtest (CSCV, 16 blocchi): quante volte la configurazione migliore in-sample finisce sotto la mediana out-of-sample. |
|
||||
| **Falsificazione** | I test di §9.2: ZScore contro PipDivergence, averaging on/off, con e senza stop, cost gate a 2×/3×/4×, segnale invertito. Servono a rompere il risultato, non a confermarlo. |
|
||||
| **Forward test** | Il periodo in Demo con metrica, soglia e durata scritte prima (`knowledge/preregistrazione.csv`). |
|
||||
| **Blackout** | Niente entrate 45 minuti prima e 30 dopo un evento ad alto impatto sulle valute del basket. |
|
||||
| **PSI** | Population Stability Index: misura la deriva della distribuzione di una feature rispetto all'addestramento. |
|
||||
| **HAR-RV** | Modello eterogeneo autoregressivo della varianza realizzata (medie a 1, 5, 22 giorni). |
|
||||
| **PSI** | Population Stability Index: misura la deriva della distribuzione di una feature rispetto all'addestramento (non collegato a niente: va reintrodotto quando il meta-modello sarà attivabile). |
|
||||
| **HAR-RV** | Modello eterogeneo autoregressivo della varianza realizzata (medie a 15 minuti, 4 ore e 24 ore). |
|
||||
| **Run id** | Identificatore della sessione del bot, scritto in ogni riga del ledger con l'hash di `strategy.json`. |
|
||||
| **Snapshot** | La fotografia immutabile dello stato del motore (conto, basket, contatori, contesto) che il server serializza in JSON e manda alla pagina una volta al secondo. La UI non ha altro. |
|
||||
| **SSE** | Server-Sent Events: la rotta `/api/stream` che spinge uno snapshot al secondo al browser. |
|
||||
| **Token web** | `ENCELADO_WEB_TOKEN`: la stringa che apre l'interfaccia; senza, il server ascolta solo su localhost. |
|
||||
| **Valuta di visualizzazione** | La valuta con cui la pagina mostra gli importi (`ui.displayCurrency`); conversione solo in presentazione con il tasso delle quotazioni, ledger sempre in USD. |
|
||||
| **Modalità campione** | `--sample`: il server serve uno snapshot finto e non avvia il motore; per lavorare sulle pagine e fotografarle. |
|
||||
| **Navigation rail** | La colonna di navigazione a sinistra (Dashboard, Storico ordini, Log, Impostazioni), 80 o 256 px. |
|
||||
| **Vista pubblicata** | La fotografia immutabile dello stato del motore (`EngineView`) che il thread di decisione pubblica dopo ogni giro, quotazione, transizione, comando e riconciliazione. Web, console e Telegram leggono solo quella (ADR-0012). |
|
||||
| **Tick** | Il JSON che il server manda alla pagina una volta al secondo (v2, `docs/API.md`): stato, allarmi, conto, basket, quotazioni, salute, apprendimento, le righe di log nuove e le versioni delle sezioni. Costruito una volta per tutti i browser. |
|
||||
| **Sezione a richiesta** | Le parti pesanti (posizioni, mercato, dettaglio basket, sistema, apprendimento) lette dalla pagina con `ETag` solo quando la loro versione nel tick cambia. |
|
||||
| **SSE** | Server-Sent Events: la rotta `/api/stream` che spinge il tick al browser, uno al secondo. |
|
||||
| **Password interfaccia** | `ENCELADO_PASSWORD` (alias deprecato `ENCELADO_WEB_TOKEN`): apre l'interfaccia e cifra i segreti. Senza, il server ascolta solo su localhost e non chiede niente. |
|
||||
| **Deposito dei segreti** | `/config/secrets.enc`: chiavi eToro dei due conti e token Telegram, cifrati con la password (AES-256-GCM). Stati: aperto, vuoto, bloccato (password cambiata: si sblocca con la precedente o si ricomincia), chiave locale (sviluppo senza password). |
|
||||
| **Importazione una tantum** | Al primo avvio della 5.1 le variabili e i file della 5.0 (chiavi, token, chat, alcune impostazioni) passano nel deposito e in `encelado.json`; poi le variabili rimaste sono ignorate e segnalate (`import-5.1.json`). |
|
||||
| **Applicazione a caldo** | Ogni impostazione salvata ha un momento d'effetto: ⚡ subito nel processo, ⚙ nel motore in esecuzione (sul thread di decisione), ↻ con un riavvio automatico del motore che non chiude niente (Live: con la frase). |
|
||||
| **Valuta di visualizzazione** | La valuta con cui la pagina mostra gli importi (`ui.displayCurrency`, Impostazioni ▸ Interfaccia); conversione solo nel browser con il tasso delle quotazioni, ledger sempre in USD. |
|
||||
| **Modalità campione** | `--sample`: il server serve dati d'esempio per ogni rotta e non avvia il motore; lavora in cartelle temporanee, non tocca configurazione, segreti, dati né Telegram, e rifiuta ogni scrittura. Per lavorare sulle pagine e fotografarle. |
|
||||
| **Pill del motore** | Nella barra in alto: pallino dello stato (verde in esecuzione, grigio fermo, ambra in avvio/arresto o con entrate bloccate, rosso in errore o bloccato) e il conto (`DEMO`, `LIVE` su fondo rosso). |
|
||||
| **Orologi delle valute** | Nella barra in alto, uno per fuso delle valute trattate (Nuova Zelanda, Australia, Europa centrale/Svizzera, USA/Canada) con le bandiere, più il fuso del computer solo se diverso (D-49). |
|
||||
| **Menu** | La colonna a sinistra con le nove pagine (Dashboard, Basket, Posizioni, Mercato, Storico, Apprendimento, Log, Sistema, Impostazioni), 212 o 56 px. |
|
||||
@@ -1,10 +1,11 @@
|
||||
# Problemi noti e limiti
|
||||
|
||||
Aggiornato: 2026-09-23. Una voce per limite, con lo stato. Quando un limite viene rimosso, la voce si sposta nel `CHANGELOG.md`.
|
||||
Aggiornato: 2026-10-01 (5.1). Una voce per limite, con lo stato. Quando un limite viene rimosso, la voce si sposta nel `CHANGELOG.md`.
|
||||
|
||||
## Strategia
|
||||
|
||||
- **Il backtest è negativo.** Su 7,75 anni di barre M15 nessuna configurazione della griglia è profittevole al netto dei costi assunti; il break-even è vicino a zero, cioè il segnale non ha contenuto misurabile (`docs/STRATEGY.md`). Il modulo resta uno strumento di forward test in Demo, non un sistema da mettere sul reale.
|
||||
- I numeri del backtest in `docs/STRATEGY.md` §3 sono del 2026-09-16: precedono i limiti di margine della 5.0 e il blocco della perdita giornaliera fino a mezzanotte della 5.1. Vanno rifatti prima di trarne altre conclusioni (il segno del verdetto non dovrebbe cambiare).
|
||||
- **EURAUD** ha tick solo per parti del 2018, 2021 e 2026: il basket EURAUD/AUDCAD è misurabile in backtest solo su quei tratti.
|
||||
- Il backtest non ha calendario né notizie: blackout e sentiment sono attivi solo dal vivo. L'effetto del blackout sui risultati non è misurato.
|
||||
- **Il cancello di correlazione ρ_W ≤ −0,6 si apre di rado sulle barre M15**: nelle 4 ore di Demo del 2026-09-16 31 segnali su 31 sono stati rifiutati per quel solo motivo. Non è un bug: è la soglia della specifica; va misurata sul ledger prima di proporre un valore diverso (`knowledge/proposals.csv`).
|
||||
@@ -18,31 +19,48 @@ Aggiornato: 2026-09-23. Una voce per limite, con lo stato. Quando un limite vien
|
||||
- Il conto reale dell'utente vale 224,90 USD (2026-09-23): con l'esposizione minima di 1000 USD per gamba il Live non è praticabile a prescindere dai cancelli.
|
||||
- **Il server non registra l'`x-request-id` come `referenceId`** degli ordini v2: il lookup per riferimento risponde 404 anche per ordini eseguiti. Dalla 5.0 l'esito si legge per `orderId`; il riferimento resta solo come ripiego (ADR-0009).
|
||||
- **A margine esaurito il server riduce l'ordine** a un importo fisso (2 000 USD di margine osservati il 16-21/9) invece di rifiutarlo; la regola non è documentata nell'OpenAPI. Il bot registra `unita_richieste` e `unita_eseguite` in `orders.jsonl` e dimensiona la gamba B sulle unità eseguite di A; i limiti di margine della Fase 2 evitano di arrivarci.
|
||||
- **La risposta di chiusura non ha il profitto** (solo `proceeds`, margine più profitto): il realizzato si legge dallo storico, che arriva da qualche secondo a qualche minuto dopo la chiusura. Fino ad allora «P&L oggi» porta una stima segnata «stima»; dopo 30 minuti senza storico la riga di `baskets.csv` viene scritta con la stima e non addestra niente (ADR-0011).
|
||||
|
||||
## Dati scritti dalla 4.0.0 alla 5.0.0
|
||||
|
||||
- **I messaggi Telegram e le righe di log già inviati** dalla 4.0.0 alla 5.0.0 mostravano i proceeds delle chiusure come «netto» e «P&L oggi» (per esempio 47 000 USD su 139 000 di equity): restano come sono, non si possono correggere. Il ledger invece è corretto con righe `correzione` (ADR-0011).
|
||||
- Le righe 4.0.x di basket con aggiunte e senza `orders.jsonl` non si possono ricondurre alle loro posizioni: restano **non verificabili** (niente etichetta, escluse da addestramento e riepiloghi). Lo stesso per le gambe singole il cui abbinamento con le note è ambiguo.
|
||||
- Un'installazione che aveva già fatto la verifica del realizzato con la prima 5.1 (nota senza `mode`) la ripete una volta, senza effetti, al primo avvio della 5.1.0, e scrive una nota per conto.
|
||||
|
||||
## Feed
|
||||
|
||||
- **Google News** vieta `/rss/search` nel `robots.txt`: le cinque query (EURUSD, SNB, RBNZ, RBA, forex) non vengono scaricate e restano vuote. SNB e RBNZ non hanno quindi nessuna fonte; RBA solo il feed ufficiale, che risponde 403 a intermittenza (Akamai). Il sentiment su CHF, NZD e in parte AUD è di fatto zero.
|
||||
- Il feed della Fed risponde 404 a tratti (osservato alle 15:16 UTC+2 del 2026-09-16): la cache copre i buchi.
|
||||
- Il calendario FairEconomy è settimanale: la settimana successiva compare solo da domenica.
|
||||
- Telegram non avvisa dei feed (calendario, RSS) in errore da più di un'ora, e la barra in alto non li mostra: lo stato di ogni fonte si vede solo in Sistema ▸ Feed (ultimo successo, errori, attesa; `health.feeds` nel tick).
|
||||
|
||||
## Bot
|
||||
|
||||
- Le posizioni salvate in `baskets_state.json` da una modalità diversa non vengono riprese (si riparte dalla riconciliazione del conto).
|
||||
- Un movimento di cassa viene riconosciuto dal salto del saldo (oltre 10 USD e 0,25 %): un accredito piccolo sotto quella soglia passa per rumore; un prelievo che coincide con una chiusura viene distinto solo se lo storico del conto risponde.
|
||||
- Telegram non avvisa dei feed (calendario, RSS) in errore da più di un'ora: il provider dei feed non espone l'ora dell'ultimo successo; il riquadro «Telegram» della dashboard mostra solo lo stato del canale.
|
||||
- Le sezioni `risk`, `recovery` e `learning` di `strategy.json` non compaiono nel form di Impostazioni (si modificano nel file, come tutto il resto della strategia); Impostazioni ▸ Ricerca mostra lo stato dell'apprendimento in sola lettura.
|
||||
- Il ciclo settimanale gira solo mentre il bot è acceso la domenica dopo le 10 UTC (o al primo avvio dopo sette giorni).
|
||||
- Un movimento di cassa del demo che coincide con un'esecuzione ridotta dal server (il caso del 16-21/9) viene riconosciuto solo se il salto del saldo non è spiegato dalle chiusure: il matching è per differenza, non per una rotta dell'API.
|
||||
- **Una gamba aperta e chiusa fra due riconciliazioni** (20 s; per esempio una gamba A richiusa subito per leg-risk) non entra mai nell'elenco delle posizioni viste: se il suo risultato supera la tolleranza (10 USD o lo 0,25 % del saldo) il salto del saldo viene giudicato un movimento di cassa, e quella perdita sfugge all'equity stop e alla perdita giornaliera. La riga di `baskets.csv` e «P&L oggi» restano giusti (vengono dallo storico). Da correggere aggiungendo all'elenco le posizioni in coda di regolamento.
|
||||
- **Kill-switch interni**: il kill-switch del file `STOP` e l'equity stop non passano dal supervisore come comandi, quindi FERMA o un riavvio automatico possono interromperli a metà. Il residuo viene registrato e il blocco salvato forza l'uscita dei basket ripresi all'avvio successivo; chiuderlo del tutto richiede un'indicazione «occupato» del motore.
|
||||
- **L'heartbeat si scrive all'inizio di ogni giro del ciclo**: un kill-switch o una chiusura che durano minuti fanno risultare il container non sano (`/api/health`); un sistema che riavvia i container non sani potrebbe interrompere un kill-switch.
|
||||
- Le chiusure fatte all'arresto con `run.closeOnShutdown` sono scritte con `exit_reason = kill_switch`: un codice proprio (per esempio `arresto`) sarebbe più onesto, ma tocca il vocabolario del ledger e le etichette dell'interfaccia.
|
||||
- Le coppie dei basket cambiate a mano in `strategy.json`, seguite da un salvataggio qualsiasi che tocca il motore, riavviano il motore senza la guardia del cambio (quella del cambio dalle Impostazioni): i basket delle coppie vecchie non vengono ripresi e la riconciliazione li chiude come orfane.
|
||||
- Il ciclo settimanale gira solo con `learning.enabled` e `learning.weeklyCycle` accesi, mentre il bot è acceso la domenica dopo le 10 UTC (o al primo avvio dopo sette giorni); «Esegui ciclo» funziona sempre.
|
||||
- **Apprendimento**: il vettore che il modello vivo valuta alla chiusura di barra ha `costPips` a 0 (il costo dell'ingresso non è ancora calcolato) e `buy_cross` senza l'eventuale inversione del segnale, mentre la riga d'ingresso su cui il ciclo addestra ha i valori veri; per questo a motore fermo la pagina dice spesso «ricalcolata con il modello di oggi» per i basket piatti. Un ingresso completato dopo un riavvio a metà (gamba in attesa) non ha il vettore della decisione e non diventa una riga di addestramento.
|
||||
|
||||
## Container e interfaccia web
|
||||
|
||||
- Il server non ha TLS: l'interfaccia è pensata per la rete locale (Unraid) o dietro un reverse proxy che lo aggiunge. Senza `ENCELADO_WEB_TOKEN` ascolta solo su localhost del container.
|
||||
- Il server non ha TLS: l'interfaccia è pensata per la rete locale (Unraid) o dietro un reverse proxy che lo aggiunge. Senza `ENCELADO_PASSWORD` ascolta solo su localhost del container.
|
||||
- **Dietro un reverse proxy** il proxy deve passare l'`Host` originale o `X-Forwarded-Host`, altrimenti ogni salvataggio e ogni comando ricevono 403 (Nginx Proxy Manager, SWAG, Caddy e Traefik lo fanno da soli; un nginx scritto a mano vuole `proxy_set_header Host $host`). Il proxy fa sembrare tutti i client un solo indirizzo: l'attesa dopo una password errata vale per tutti (fidarsi di `X-Forwarded-For` richiederebbe un'impostazione dei proxy fidati, che non esiste).
|
||||
- Le righe di `baskets.csv` e di `decisions.jsonl` scritte dalla 5.0 portano nel `mode` la modalità, non il conto: con `Live` accanto a `etoro.environment` demo (o `Demo` accanto a `real`) la verifica del realizzato le cerca sul conto sbagliato (un motore Live le dichiara non verificabili, uno Demo non le guarda) e finché non succede restano con l'etichetta dei proceeds. Lo stato della 5.0 invece va al conto giusto (la registrazione dell'importazione, `legacyState`). Con la configurazione di fabbrica della 5.0 (Demo e demo) il problema non c'è.
|
||||
- Il registro dei container di Gitea è in HTTP: chi fa `docker pull` deve dichiararlo `insecure-registry` (Docker Desktop e Unraid, vedi `docs/DOCKER.md`).
|
||||
- **Gitea Actions senza runner**: `ci.yml` e `release.yml` restano in coda finché sul server non c'è un runner (e il segreto `REGISTRY_TOKEN`); il rilascio si fa dal PC con la catena (`docs/DOCKER.md`).
|
||||
- Il template Unraid non è pubblicato in un repository di template della community: si installa dall'URL raw del file (`deploy/unraid/README.md`).
|
||||
- La valuta di visualizzazione usa il tasso della quotazione più recente ricevuta dal polling; con il mercato chiuso il tasso invecchia e il tooltip lo dice.
|
||||
- L'interfaccia pesa circa 295 KB di JavaScript non minificato (90 KB con gzip) e Kestrel non comprime i file statici.
|
||||
- Mercato: a 1440 px la colonna «Età» delle quotazioni sparisce (la sezione è stretta); Storico: il motivo d'uscita lungo (rientro dello z-score) finisce con i puntini, intero nel tooltip.
|
||||
- Log: la ricerca usa il testo del file (il `q` del server), quindi trova `tp_pips` ma non «take-profit», che è l'etichetta italiana mostrata a schermo.
|
||||
|
||||
## Codice
|
||||
|
||||
- `BasketEngine` è spezzato in sei file parziali dalla 5.0; il file principale resta di ~900 righe (loop, decisioni, esecuzione).
|
||||
- I test dell'interfaccia coprono l'HTML incorporato, il JSON dello snapshot, il token e lo stream (`EmbeddedUiTests`, `WebHostTests`), non il comportamento della pagina nel browser (JavaScript, dialoghi): quello si controlla a occhio con `--sample` e con gli screenshot in `docs/img/`.
|
||||
- `BasketEngine` è spezzato in undici file parziali; il file principale resta di ~1 800 righe (loop, decisioni, esecuzione).
|
||||
- I test dell'interfaccia (`EmbeddedUiTests`, `WebHostTests`) coprono l'HTML incorporato, ogni `import` dei moduli con i nomi esportati, i file serviti con il loro tipo, la password, il cookie e lo stream, non il comportamento della pagina nel browser (JavaScript, dialoghi): quello si controlla con `--sample`, con gli screenshot in `docs/img/` e con i controlli nel browser della revisione, che non stanno nel repository.
|
||||
- Il test (l) copre i blocchi nel decisore, non la simulazione completa dell'equity stop nel motore live; quella è coperta dal backtest (`EquityStops` in `BacktestResult`) e dal ledger.
|
||||
@@ -4,7 +4,7 @@ Regole comuni: UTC ovunque, `CultureInfo.InvariantCulture` per numeri e date, CS
|
||||
|
||||
## `data/ledger/decisions.jsonl`
|
||||
|
||||
Una riga per **ogni** valutazione di ogni basket alla chiusura di ogni barra M15 (ingresso, skip, aggiunta, posizione, uscita) più le uscite decise su una quotazione intermedia e gli esiti di esecuzione. Le feature sono quelle disponibili **al momento della decisione**: è la regola anti look-ahead, e il dataset di addestramento è questo file, non una ricostruzione.
|
||||
Una riga per **ogni** valutazione di ogni basket alla chiusura di ogni barra M15 (ingresso, skip, aggiunta, posizione, uscita) più le uscite decise su una quotazione intermedia e gli esiti di esecuzione. Le feature sono quelle disponibili **al momento della decisione**: è la regola anti look-ahead, e il dataset di addestramento è questo file, non una ricostruzione. Il file ruota ogni mese in `decisions_YYYYMM.jsonl`, solo in avanti (dalla 5.1: una riga tardiva del mese precedente, come l'ultima barra valutata dopo la mezzanotte, resta nel file corrente con la sua ora; un nome già preso diventa `decisions_YYYYMM_02.jsonl`, che si ordina subito dopo). Chi legge il ledger legge tutti i file `decisions*.jsonl`.
|
||||
|
||||
| Campo | Tipo | Significato |
|
||||
|---|---|---|
|
||||
@@ -14,9 +14,9 @@ Una riga per **ogni** valutazione di ogni basket alla chiusura di ogni barra M15
|
||||
| `basket` | testo | `A/B`, es. `EURUSD/USDCHF` |
|
||||
| `basket_id` | testo | id del basket aperto (`B<yyyyMMddHHmmss>-<AB>`), vuoto se piatto; collega a `baskets.csv` |
|
||||
| `cross` | testo | cross sintetico (`EURCHF`) |
|
||||
| `mode` (`Paper` | `Demo` | `Live`; i file scritti prima del 2026-09-16 pomeriggio portano i nomi precedenti `DemoApprove`/`DemoAuto`) | testo | `Paper`, `Demo`, `Live` |
|
||||
| `mode` | testo | `Demo` o `Live`, cioè il conto (dalla 5.1 la modalità sceglie il conto). Le righe storiche portano anche `Paper` (fino alla 5.0.0, mai riscritte e mai contate come Demo) e, prima del 2026-09-16 pomeriggio, `DemoApprove`/`DemoAuto`/`LiveApprove`/`LiveAuto` (contate come Demo e Live) |
|
||||
| `preset` | testo | `CONSERVATIVE`, `MODERATE`, `AGGRESSIVE` |
|
||||
| `evento` | testo | `skip`, `segnale_ingresso`, `ingresso`, `rifiuto`, `leg_risk_unwind`, `posizione`, `segnale_aggiunta`, `aggiunta`, `segnale_uscita`, `uscita`, `correzione`; dalla 5.0 anche le righe di evento (senza feature, solo `ts`, `run_id`, `evento`, `basket_id`, campi propri e `motivazione`): `pending` (gamba senza esito, con `leg`, `client_ref`, `order_id`), `pending_risolto` (con `esito`, `fonte`, `position_id`), `orfana_adottata` e `orfana_chiusa` (con `position_id`, `strumento`, `pnl`, `exit_reason`), `movimento_di_cassa` (con `importo`, `saldo_prima`, `saldo_dopo`, `chiusure_nel_frattempo`, `cassa_cumulata`), `margin_guard` (con `equity`, `margine_usato`), `kill_switch_avviato`, `kill_switch_concluso` (con `stato` = `Halted` o `Halted-Residuo`, `chiuse`, `residuo`, `annullati`, `pnl`), `residuo_chiuso`, `reset_rifiutato`, `reset_concluso`, `recupero_avviato` (con `inattivita_min`, `barre`), `recupero_concluso` (con `inattivita_min`, `barre`, `chiusi`, `tenuti`), `comando` (ogni comando dalla finestra, dalla console o da Telegram: `comando`, `argomento`, `ok`; la motivazione porta l'origine e la prima riga dell'esito) |
|
||||
| `evento` | testo | `skip`, `segnale_ingresso`, `ingresso`, `rifiuto`, `leg_risk_unwind`, `posizione`, `segnale_aggiunta`, `aggiunta`, `segnale_uscita`, `uscita`, `correzione`; dalla 5.0 anche le righe di evento (senza feature, solo `ts`, `run_id`, `evento`, `basket_id`, campi propri e `motivazione`): `pending` (gamba senza esito, con `leg`, `client_ref`, `order_id`), `pending_risolto` (con `esito`, `fonte`, `position_id`), `orfana_adottata` e `orfana_chiusa` (con `position_id`, `strumento`, `exit_reason` e, fino alla 5.0.0, `pnl` = il `proceeds` della chiusura; dalla 5.1 `stima`), `movimento_di_cassa` (con `importo`, `saldo_prima`, `saldo_dopo`, `chiusure_nel_frattempo`, `cassa_cumulata`), `margin_guard` (con `equity`, `margine_usato`), `kill_switch_avviato` (dalla 5.1 con `esterne` = se il kill-switch chiude anche le posizioni esterne ed `esterne_da` = `comando` quando l'ha scelto chi l'ha lanciato — la casella del dialogo, la risposta della console — o `impostazione` quando vale `risk.closeForeignOnKill`), `kill_switch_concluso` (con `stato` = `Halted` o `Halted-Residuo`, `chiuse`, `residuo`, `annullati` e, fino alla 5.0.0, `pnl` = somma dei `proceeds`; dalla 5.1 `pnl_bot` e `pnl_esterne` — stime dai prezzi di chiusura, le posizioni del bot separate da quelle esterne —, `pnl_bot_sconosciuti`, `pnl_esterne_sconosciuti`, `pnl_fonte`), `kill_switch_interrotto` (dalla 5.1: l'arresto del processo ha interrotto un kill-switch in corso dopo 30 s; `residuo` = quante posizioni note del bot sono state registrate come residuo, stato `Halted-Residuo`), `residuo_chiuso`, `reset_rifiutato`, `reset_concluso`, `recupero_avviato` (con `inattivita_min`, `barre`; dalla 5.1 anche per un conto i cui basket nessuno ha seguito oltre la soglia mentre il bot girava sull'altro), `recupero_concluso` (con `inattivita_min`, `barre`, `chiusi`, `tenuti`), `comando` (ogni comando dall'interfaccia, dalla console o da Telegram: `comando` = il tipo — `Close`, `KillSwitch`, `ResetEquityStop`, `CloseResidue`, `Bonifica`, `History`, `Pause`, `Resume`, `ApplySettings`, `Learn`, e dalla 5.1 `Shutdown` (argomento `chiudi`, la chiusura all'arresto con `run.closeOnShutdown`), `PrepareAccountSwitch` e `CancelAccountSwitch` (il controllo del cambio di conto) —, `argomento`, `ok`; la motivazione porta l'origine e la prima riga dell'esito; dalla 5.1 anche i comandi mai eseguiti o interrotti dall'arresto del motore, con `ok = false` e «comando interrotto: il motore si è fermato»), `configurazione` (dalla 5.1: un salvataggio delle impostazioni applicato dal motore in esecuzione; `config_hash_precedente`, `config_hash`, `preset`, `chiavi` = i percorsi cambiati); la nota `leg_risk_unwind` (gamba A eseguita in ritardo e richiusa) porta `position_id` e fino alla 5.0.0 `pnl` (proceeds), dalla 5.1 `stima`. Dalla 5.1: `realizzato` (una chiusura regolata sullo storico eToro: `basket`, `exit_reason`, `fonte` = `storico eToro` / `stima dai prezzi di chiusura` / `simulatore`, `position_ids`, `pnl_lordo`, `pnl_netto`, `stima` = il valore stimato alla chiusura) e `verifica_realizzato` (la verifica del realizzato all'avvio: `mode` = il conto verificato, `fino_a` = ora di chiusura dell'ultima riga verificata, `righe`, `concordi`, `corrette`, `non_verificabili`; la motivazione dice «… (conto Demo)»). La nota `ingresso` (un ingresso completato dopo una gamba in attesa, senza riga di valutazione propria) dalla 5.1 porta `basket`, l'array `features` (il vettore della decisione che ha aperto il basket) e `p_ML`, quando il motore li ha ancora; dopo un riavvio a metà ingresso non li ha, e quel basket non diventa una riga di addestramento. I testi «netto … USD» delle righe `uscita` e `residuo_chiuso` fino alla 5.0.0 sono proceeds; dalla 5.1 dicono «stima … in attesa dello storico eToro» |
|
||||
| `decision` | testo | `Skip`, `Enter`, `Add`, `Exit`, `Hold` |
|
||||
| `buy_cross` | bool | verso deciso (compra il cross = compra entrambe le gambe nei cinque basket) |
|
||||
| `z`, `z_in_eff` | numero | z-score del cross e soglia effettiva (scalata dalla vol prevista) |
|
||||
@@ -32,8 +32,8 @@ Una riga per **ogni** valutazione di ogni basket alla chiusura di ogni barra M15
|
||||
| `minutesToNextHigh`, `minutesSinceLastHigh`, `surpriseLast` | numero/null | calendario per le valute del basket |
|
||||
| `netSentDiff_1h/4h/24h`, `hawkishDiff`, `riskOff`, `newsCount` | numero | sentiment (valuta lunga − valuta corta del cross) |
|
||||
| `regimeTrend` | numero | forza di trend (ADX-like) del cross |
|
||||
| `lastNOutcomes` | numero | media degli ultimi esiti (null finché non c'è storia) |
|
||||
| `p_ML`, `mlActive` | numero, bool | probabilità del meta-modello e se è gate o ombra |
|
||||
| `lastNOutcomes` | numero | media degli ultimi esiti (null finché non c'è storia); dalla 5.1 gli esiti vengono dal ledger corretto, riletto dopo la verifica del realizzato all'avvio |
|
||||
| `p_ML`, `mlActive` | numero, bool | probabilità del meta-modello e se è gate o ombra. Dalla 5.1 un basket aperto ripreso dopo un riavvio porta nelle sue righe la `p_ML` del suo ingresso (prima era vuota) |
|
||||
| `equity`, `openBaskets` | numero | equity e basket aperti al momento |
|
||||
| `priceA`, `priceB`, `pipsOpen`, `pnlOpenUsd`, `barsHeld` | numero | stato della posizione (se aperta) |
|
||||
| `unitsA`, `unitsB`, `notionalUsd`, `lossAtStopUsd`, `effectiveLeverage`, `marginUsd` | numero | sizing (solo su `Enter`); `marginUsd` = margine previsto delle due gambe (5.0) |
|
||||
@@ -41,15 +41,37 @@ Una riga per **ogni** valutazione di ogni basket alla chiusura di ogni barra M15
|
||||
| `reasonCodes` | array | codici: `no_signal`, `rho_low`, `rho_short_low`, `half_life`, `blackout_before`, `blackout_after`, `weekend`, `just_opened`, `session`, `max_baskets`, `same_cross`, `ml_gate`, `cost_gate`, `sizing`, `kill_switch`, `equity_stop`, `daily_loss`, `entries_blocked`, `data_quality`, `warmup`, `not_bar_close`, `enter`, `add`, `hold`, `tp_pips`, `tp_z`, `stop_z`, `stop_max_loss`, `spread_anomaly`, `time_stop`, `rho_break`; dalla 5.0 `margin` (nessun margine per un nuovo basket), `margin_guard` (equity / margine usato sotto la soglia), `min_exposure` (la size a margine non raggiunge l'esposizione minima) |
|
||||
| `motivazione` | testo | la frase, in italiano, con i numeri |
|
||||
|
||||
### Correzioni (`evento = correzione`)
|
||||
|
||||
Una correzione è sempre una riga nuova: `baskets.csv` e le righe già scritte non cambiano mai. Oltre alle correzioni libere (motivazione del reset, equity stop; fino alla 5.0 anche il cambio di preset a caldo, che dalla 5.1 non esiste più: un cambio di strategia è una riga `configurazione`), dalla 5.1 esistono tre `tipo`:
|
||||
|
||||
| `tipo` | Campi | Significato |
|
||||
|---|---|---|
|
||||
| `pnl_realizzato` | `riga` (chiave della riga di `baskets.csv`: `basket_id` + `|` + `closed_utc` nel formato `O`, così si distinguono anche le gambe singole con `basket_id` vuoto), `basket`, `exit_reason`, `pnl_net_registrato`, `pnl_gross_corretto`, `pnl_net_corretto`, `label_corretta`, `verificata`, `position_ids`, `fonte` | il realizzato vero di una riga, dallo storico eToro (`netProfit − fees` delle sue posizioni). Con `verificata = false` (posizioni non ritrovate) i tre campi corretti sono `null`: la riga non ha etichetta, non addestra niente ed è esclusa dai riepiloghi. La scrive la verifica del realizzato all'avvio (`verifica_realizzato`), idempotente: una riga verificata non viene più controllata |
|
||||
| `feature_inaffidabile` | `feature` (`lastNOutcomes`), `indice` (26), `fino_a` | la feature è inaffidabile in ogni riga di valutazione scritta prima di `fino_a`: era calcolata sulle etichette sbagliate. Nel dataset vale il suo valore neutro 0,5; mai ricostruita a posteriori. Vale la riga con il `fino_a` più recente: una seconda riga arriva quando un avvio sull'altro conto corregge righe della 4.0-5.0 dopo il ritiro dei modelli (le sessioni intermedie avevano calcolato la feature anche con quelle etichette) |
|
||||
| `pnl_note_proceeds` | `da`, `a` | nelle righe scritte in quell'intervallo i campi `pnl` delle note (`leg_risk_unwind`, `orfana_chiusa`, `kill_switch_concluso`) e i testi «netto … USD» sono i `proceeds` della chiusura, non il P&L. Nessun codice li legge |
|
||||
|
||||
**La verifica all'avvio** (`RealizedBackfill`) lavora sul conto in uso: controlla solo le righe di quel conto (le modalità della 4.0 `DemoApprove`/`DemoAuto` contano come Demo, `LiveApprove`/`LiveAuto` come Live; le righe `Paper` mai) chiuse dopo l'ultima nota `verifica_realizzato` **dello stesso conto** (dalla 5.1 la nota porta `mode`; una nota senza `mode`, scritta dalla prima 5.1, non conta: la verifica si ripete una volta, senza effetti), più le righe ancora non verificabili e quelle scritte con la stima. Le posizioni di una riga vengono dal marcatore `posizioni:` della motivazione, da `orders.jsonl` (le aggiunte richiuse escluse), dai prezzi d'esecuzione delle note `ingresso` della 4.0.x o, per una gamba singola, dalla sua nota (`leg_risk_unwind`, `orfana_chiusa`): le note si abbinano alle righe tutte insieme, solo con lo stesso `basket_id` (vuoto con vuoto), lo stesso motivo d'uscita e strumento, entro 120 s, una nota per riga e in ordine di tempo; un abbinamento ambiguo lascia la riga non verificabile invece di indovinare.
|
||||
|
||||
**Lettore corretto** (`Ledger.ReadBasketsCorrected`): legge `baskets.csv` e applica a ogni riga la correzione `pnl_realizzato` più recente della sua chiave, cercandola in tutti i `decisions*.jsonl` (mesi ruotati compresi); marca non verificata (`Unverified`, niente etichetta) una riga con correzione non verificata, con P&L sconosciuto o scritta come stima dopo il timeout (`P&L: stima` nella motivazione). Lo usano il dataset di addestramento, il seme di `lastNOutcomes`, il riepilogo giornaliero e `/storico` di Telegram, la scheda Storico. Il file non viene mai toccato.
|
||||
|
||||
**Cosa non si può correggere**: i messaggi Telegram e le righe di log già emessi dalla 4.0.0 alla 5.0.0 mostravano i proceeds come «netto» e «P&L oggi»; restano come sono.
|
||||
|
||||
## `data/ledger/baskets.csv`
|
||||
|
||||
Una riga per basket chiuso. `label = 1` se `pnl_net_usd > 0`, altrimenti 0: è l'etichetta dei livelli 1-3.
|
||||
Una riga per basket chiuso (e per gamba singola). `label = 1` se `pnl_net_usd > 0`, altrimenti 0: è l'etichetta dei livelli 1-3; vuota quando il P&L è sconosciuto.
|
||||
|
||||
```
|
||||
basket_id;run_id;basket;mode;preset;opened_utc;closed_utc;buy_cross;entry_z;exit_z;pnl_gross_usd;pnl_net_usd;pips_gross;cost_pips;cost_usd;slippage_pips;adds;bars_held;exit_reason;equity_at_entry;p_ml_at_entry;label;durata_min;motivazione
|
||||
```
|
||||
|
||||
`pips_gross` è la somma dei pip delle due gambe ai prezzi di esecuzione (la colonna "Pips" della UI), `cost_pips` il costo stimato all'ingresso, `slippage_pips` la differenza fra quotazione vista e prezzo eseguito sommata sulle gambe, `exit_reason` uno dei codici sopra più `manual`, `closed_by_broker`, `leg_closed_by_broker`, `end_of_data`, e dalla 5.0 `leg_risk_unwind` (gamba A eseguita in ritardo e richiusa, o B non coperta dal margine), `margin_guard` (chiuso dalla guardia del margine), `orphan_closed` (gamba orfana del bot adottata e chiusa alla riconciliazione), `bonifica_orfana` (chiusa dalla bonifica con conferma), `kill_switch`/`equity_stop` anche per le gambe singole. Le righe di una gamba singola hanno `entry_z`, `exit_z`, `pips_gross` e `cost_*` vuoti e `buy_cross` = verso della gamba.
|
||||
**Da dove viene il P&L (dalla 5.1).** eToro non dice il realizzato nella risposta di chiusura. La riga non viene scritta alla chiusura: resta nella coda di regolamento (`pendingSettlements` dello stato) con la **stima** dai prezzi di chiusura e viene scritta quando lo storico eToro mostra tutte le sue posizioni, con `pnl_net_usd = Σ (netProfit − fees)` e `pnl_gross_usd = Σ netProfit`; la motivazione finisce con `| P&L: storico eToro (netProfit − fees)`. Se dopo 30 minuti lo storico non le mostra ancora, la riga viene scritta con la stima e la motivazione finisce con `| P&L: stima dai prezzi di chiusura…`: non addestra niente e la verifica all'avvio la ricontrolla finché lo storico non la conferma. In un simulatore (backtest) il numero è quello finale del simulatore (`| P&L: simulatore`). La motivazione porta anche `posizioni: <id> <id> …`, le posizioni eToro della riga. **Fino alla 5.0.0** `pnl_net_usd` era la somma dei `proceeds` delle chiusure (margine restituito + profitto) meno l'overnight maturato, e `label` quasi sempre 1: quelle righe si leggono solo con il lettore corretto.
|
||||
|
||||
**Una posizione, una riga (dalla 5.1).** Una posizione eToro finisce in `baskets.csv` una volta sola: il motore ricorda le posizioni già scritte (il marcatore `posizioni:` delle righe del suo conto) e quelle in coda di regolamento, e nessun percorso (uscita del basket, chiusura dei residui, riconciliazione, orfana richiusa da un elenco vecchio) le registra di nuovo. Le gambe di un basket rimaste nel residuo di un kill-switch diventano, quando sono tutte chiuse, **una** riga del basket con `exit_reason = kill_switch` e titolo «Basket chiuso: …». Prima una chiusura vista da due percorsi poteva comparire due volte e raddoppiare il P&L dei riepiloghi.
|
||||
|
||||
**Preset (dalla 5.1)**: la colonna `preset` è il preset con cui il basket è **entrato** (salvato nel basket e nell'ingresso in sospeso), anche nelle righe `closed_by_broker`; le righe di una gamba singola di un'aggiunta o di un ingresso richiusi portano il preset del loro basket o del loro tentativo. Fino alla prima 5.1 era il preset in vigore alla chiusura.
|
||||
|
||||
`pips_gross` è la somma dei pip delle due gambe ai prezzi di esecuzione (la colonna "Pips" della UI), `cost_pips` il costo stimato all'ingresso, `slippage_pips` la differenza fra quotazione vista e prezzo eseguito sommata sulle gambe, `exit_reason` uno dei codici sopra più `manual`, `closed_by_broker`, `leg_closed_by_broker`, `end_of_data`, e dalla 5.0 `leg_risk_unwind` (gamba A eseguita in ritardo e richiusa, o B non coperta dal margine; dalla 5.1 anche la gamba A di un'aggiunta richiusa, con il `basket_id` del basket), `margin_guard` (chiuso dalla guardia del margine), `orphan_closed` (gamba orfana del bot adottata e chiusa alla riconciliazione), `bonifica_orfana` (chiusa dalla bonifica con conferma), `kill_switch`/`equity_stop` anche per le gambe singole (e, dalla 5.1, per i basket rimasti nel residuo di un kill-switch; le chiusure fatte da `run.closeOnShutdown` all'arresto usano anch'esse `kill_switch`). Le righe di una gamba singola hanno `entry_z`, `exit_z`, `pips_gross` e `cost_*` vuoti e `buy_cross` = verso della gamba. `p_ml_at_entry`: dalla 5.1 anche un basket aperto ripreso dopo un riavvio porta la `p_ML` del suo ingresso (prima era vuota).
|
||||
|
||||
## `data/ledger/orders.jsonl` (dalla 5.0)
|
||||
|
||||
@@ -65,22 +87,40 @@ Una riga per **ogni ordine inviato** e per **ogni cambio del suo stato** (append
|
||||
| `prezzo_richiesto`, `prezzo_eseguito`, `slippage_pip` | quotazione vista all'invio, prezzo del server, differenza in pip con il segno del costo |
|
||||
| `stato`, `stato_id` | l'ultima parola del server (`Submitted`, `Received`, `Placed`, `Filled`, `Rejected`, …, `Unknown` quando non ha risposto), con l'id numerico di eToro |
|
||||
| `esito` | `Pending`, `Filled`, `Rejected`, `Cancelled` |
|
||||
| `order_id`, `position_id`, `client_ref` | le tre chiavi |
|
||||
| `order_id`, `position_id`, `client_ref` | le tre chiavi; dalla 5.1 anche le righe di chiusura (`Close`, `Unwind`) portano il `position_id` della posizione chiusa, la chiave dello storico eToro |
|
||||
| `fee` | commissioni riportate dal server all'esecuzione |
|
||||
| `evento` | `inviato`, `stato`, `risolto` |
|
||||
| `motivazione` | la motivazione della decisione o l'errore del server |
|
||||
|
||||
## `data/state/pending_orders.json` (dalla 5.0)
|
||||
|
||||
Il registro degli ordini: `savedUtc` e l'array `orders` con gli stessi campi di `orders.jsonl` più `checks`, `lastCheckUtc`, `source` (`venue`, `lookup`, `lookup-v1`, `positions`). Contiene tutti gli ordini senza esito e quelli risolti nelle ultime 48 ore (servono a riconoscere una posizione come propria). Scritto **prima** di ogni chiamata HTTP e a ogni cambio di stato, con `.tmp` + `File.Move`. Un file illeggibile viene messo da parte come `pending_orders.json.illeggibile-<data>`. In modalità Paper il file è `pending_orders_paper.json`.
|
||||
Il registro degli ordini: `savedUtc` e l'array `orders` con gli stessi campi di `orders.jsonl` più `checks`, `lastCheckUtc`, `source` (`venue`, `lookup`, `lookup-v1`, `positions`). Contiene tutti gli ordini senza esito e quelli risolti nelle ultime 48 ore (servono a riconoscere una posizione come propria). Scritto **prima** di ogni chiamata HTTP e a ogni cambio di stato, con `.tmp` + `File.Move`. Un file illeggibile viene messo da parte come `pending_orders.json.illeggibile-<data>`. **Un file solo per i due conti** (dalla 5.1): ogni ordine porta il suo `mode` e un motore vede, risolve, fa fallire e pota solo gli ordini del suo conto (quelli senza `mode`, più vecchi, appartengono a chi apre il registro); all'avvio il log dice quanti ordini senza esito ha l'altro conto. Il file `pending_orders_paper.json` della 5.0 non viene più letto.
|
||||
|
||||
## `data/state/baskets_state.json` (campi aggiunti dalla 5.0)
|
||||
## `data/state/baskets_state.demo.json` e `baskets_state.live.json` (stato del motore, uno per conto dalla 5.1)
|
||||
|
||||
`peakNetEquity` (picco dell'equity al netto dei movimenti di cassa), `cumulativeCashFlow`, `lastBalance` e `lastBalanceUtc` (per riconoscere un deposito avvenuto a bot spento), `pendingEntries` (un elemento per basket in `PendingA`/`PendingB`: `name`, `state`, `basketId` e il piano `pending` con unità, TP, stop, riferimenti cliente e la gamba A eseguita), `haltResidue` (le posizioni del bot rimaste sul conto dopo un kill-switch: `positionId`, `symbol`, `isBuy`, `units`, `openedUtc`, `origin`, `basket`, `reason`). `peakEquity` resta per compatibilità e vale `peakNetEquity + cumulativeCashFlow`.
|
||||
Lo stato che il motore riprende all'avvio, **uno per conto** (D-53): il motore del conto demo legge e scrive solo `baskets_state.demo.json`, quello del conto reale solo `baskets_state.live.json`. Scritto in modo atomico (nome temporaneo unico + rinomina) dopo ogni cambiamento che conta; non si scrive finché lo stato non è stato letto, così un avvio fallito presto non sovrascrive niente.
|
||||
|
||||
Il file unico `baskets_state.json` della 5.0 e della prima 5.1 viene spostato **una volta sola**, dal primo motore che prende il lock della cartella, al conto a cui appartiene: per un file della prima 5.1 (ha `pendingSettlements`) il conto scritto nel suo `mode`; per un file della 5.0 o della 4.0, dove `mode` era la modalità e non il conto, il conto su cui operava la configurazione della 5.0, registrato dall'importazione in `import-5.1.json` (`legacyState`: `mode` = la modalità che quel file nomina, `account` = `demo`, `live` o vuoto per Paper) — un `Live` accanto a `etoro.environment` demo è il conto demo, un `Demo` accanto a `real` il reale. Senza registrazione lo prende solo il motore della modalità che il file nomina; un file di Paper, o di una modalità diversa da quella registrata, non viene mai letto (seconda revisione). Il `mode` del file spostato diventa quello del conto; un file che nomina nessun `mode` va al motore che lo trova. Se il conto ha già il suo file vince il più recente (`savedUtc`) e l'altro resta accanto. L'originale resta come `baskets_state.json.migrato`: niente viene cancellato. File messi da parte dal motore: `.precedente` (sostituito da uno più recente nella migrazione), `.altro-conto` (un file del conto demo copiato a mano nel nome del reale, o viceversa: mai usato), `.illeggibile` (JSON rotto: il motore riparte dalla riconciliazione); se il nome è già preso si aggiunge l'ora.
|
||||
|
||||
Campi:
|
||||
|
||||
| Campo | Significato |
|
||||
|---|---|
|
||||
| `savedUtc`, `runId`, `mode` | quando, da quale run e per quale conto |
|
||||
| `peakNetEquity`, `cumulativeCashFlow` | picco dell'equity al netto dei movimenti di cassa e cassa cumulata (5.0); `peakEquity` resta per compatibilità e vale `peakNetEquity + cumulativeCashFlow` |
|
||||
| `lastBalance`, `lastBalanceUtc` | l'ultimo saldo letto, per riconoscere un deposito o un prelievo avvenuto a bot spento |
|
||||
| `lastPositionIds`, `vanishedUnsettled`, `vanishedSinceUtc` | dalla 5.1: le posizioni che l'ultima riconciliazione ha visto e quelle sparite senza ancora un verdetto sul saldo. All'avvio il saldo si giudica solo quando lo storico eToro mostra ognuna di quelle chiuse da allora |
|
||||
| `sessionDate`, `dayStartEquity` | il giorno UTC e l'equity **netta** alla prima lettura del conto del giorno: la base della perdita giornaliera |
|
||||
| `dailyLossDay` | dalla 5.1 (D-52): il giorno UTC (`yyyy-MM-dd`) in cui la perdita giornaliera è scattata, vuoto se non è scattata; un riavvio nello stesso giorno tiene il blocco, il giorno dopo lo ignora |
|
||||
| `pendingSettlements` | dalla 5.1, **al posto di `todayRealized`** (5.0, la somma dei proceeds: non viene più né scritto né letto; «P&L oggi» si ricalcola dallo storico eToro). La coda delle chiusure che aspettano lo storico, un elemento per chiusura: `key` (la chiave della riga), `rowCsv` (la riga di `baskets.csv` come verrà scritta, con la stima nei campi P&L), `ids` (le posizioni eToro), `estimate` (null se sconosciuta), `closedUtc`, `learn` (se il regolamento istruisce i modelli: solo i basket, mai le stime), `volContext` (il terzile di volatilità alla chiusura, per il bandit), `title` e `detail` (il messaggio). Un riavvio non perde niente: la coda riparte dallo stato, e le righe già scritte in `baskets.csv` vengono scartate. Con lo stato per conto le chiusure in attesa di un conto aspettano che quel conto torni a girare |
|
||||
| `pausedByOperator`, `entriesBlockedUntilUtc` | dalla 5.1: la pausa dell'operatore (`/pausa`) e il riscaldamento in corso sopravvivono a un riavvio |
|
||||
| `killSwitched`, `equityStopped`, `haltReason`, `haltResidue` | i blocchi e il residuo del kill-switch (le posizioni del bot rimaste sul conto: `positionId`, `symbol`, `isBuy`, `units`, `openedUtc`, `origin`, `basket`, `reason`) |
|
||||
| `baskets` | un elemento per basket aperto: `name`, `basketId`, `buyCross`, `openedUtc`, `entryZ`, `lastAddZ`, `adds`, `barsHeld`, `entryCostPips`, `tpPips`, `maxLossUsd`, `zStop` e `maxAdds` (dalla 5.1: quelli con cui è entrato), `preset` (dalla 5.1: il preset d'ingresso), `equityAtEntry`, `accruedFeesUsd`, `entryMotivazione`, le gambe `a` e `b` |
|
||||
| `pendingEntries` | un elemento per basket in `PendingA`/`PendingB`: `name`, `state`, `basketId` e il piano `pending` con unità, TP, perdita massima, `zStop`, `maxAdds` e `preset` (5.1), costo e equity all'ingresso, motivazione, ora della decisione, riferimenti cliente, quotazioni viste e la gamba A eseguita |
|
||||
|
||||
## `data/state/heartbeat.json` e `data/state/instance.lock` (dalla 5.0)
|
||||
|
||||
`heartbeat.json`: `{utc, run_id, mode, openBaskets, pendingBaskets, pid, note}` scritto ogni `recovery.heartbeatSeconds` (30), all'avvio (`note = avvio`) e all'arresto (`arresto`), con `.tmp` + `File.Move`. Il tempo trascorso dall'ultimo `utc` è l'inattività che fa scattare il recupero. `instance.lock`: `{pid, runId, sinceUtc, machine}`, tenuto aperto in esclusiva dal motore per tutta la sessione; non va cancellato a mano.
|
||||
`heartbeat.json`: `{utc, run_id, mode, openBaskets, pendingBaskets, pid, note}` scritto ogni `recovery.heartbeatSeconds` (30), all'avvio (`note = avvio`) e all'arresto (`arresto`), con `.tmp` + `File.Move`. Il tempo trascorso dall'ultimo `utc` è l'inattività che fa scattare il recupero; `/api/health` lo giudica vecchio oltre 3 × l'intervallo + 15 s. Il file è uno solo per i due conti: l'inattività di un conto rimasto fermo mentre il bot girava sull'altro si misura dal `savedUtc` del suo file di stato. `instance.lock`: `{pid, runId, sinceUtc, machine}`, tenuto aperto in esclusiva dal motore per tutta la sessione; non va cancellato a mano.
|
||||
|
||||
## `reports/recupero_<run_id>.csv` (dalla 5.0)
|
||||
|
||||
@@ -108,7 +148,17 @@ test;variante;n_baskets;win_rate;pnl_net;sharpe;maxdd;p1_pnl;p5_pnl;break_even_c
|
||||
|
||||
## `knowledge/calibration.csv`
|
||||
|
||||
Win rate e P&L netto medio per bucket: `dimensione;bucket;n;win_rate;pnl_medio;pnl_totale;motivazione`, con dimensioni `|z|`, `rho_W`, `ora`, `giorno`, `minuti_evento`, `sentiment`, `preset`, `basket`.
|
||||
Win rate e P&L netto medio per bucket: `dimensione;bucket;n;win_rate;pnl_medio;pnl_totale;motivazione`, con nove dimensioni: `abs_z` (soglie 1,5 / 2 / 2,5 / 3), `rho_W` (−0,9 / −0,8 / −0,7 / −0,6 / 0), `ora_utc`, `giorno`, `minuti_evento` (60 / 180 / 720), `sentiment_4h` (±0,05 / ±0,2), `preset` (il preset d'ingresso, dalla 5.1), `basket`, `verso`. Solo i basket con il P&L dello storico eToro (lettore corretto); la colonna `motivazione` dice «campione piccolo» sotto 20 basket.
|
||||
|
||||
## `data/models/` (apprendimento, dalla 5.1 un solo scrittore: chi tiene `instance.lock`)
|
||||
|
||||
| File | Contenuto |
|
||||
|---|---|
|
||||
| `logreg_current.json`, `mlp_current.json`, `bandit.json` | stato corrente dei modelli (ripreso all'avvio); `mlp_current.json` esiste solo con `learning.enabled` e `learning.challenger` accesi |
|
||||
| `logreg_vN.json`, `mlp_vN.json` | versioni dei cicli con `trained_on_until`, `trained_at`, righe, hash del dataset, `trigger` (`settimanale`, `manuale`, `offline`) e nomi delle feature |
|
||||
| `last_cycle.json` | dalla 5.1: la valutazione completa dell'ultimo ciclo (AUC con intervallo, Brier, log-loss, calibrazione, P&L di tutti e filtrati, Sharpe, DSR, attivazione con la motivazione; logistica e challenger) e il riepilogo del dataset |
|
||||
| `learning_state.json` | schema 2 (dalla 5.1; legge anche quello della 5.0): `schema`, `active`, `champion`, `version`, `lastCycleUtc`, `lastReport`, `labelsFixedUtc` (quando i modelli addestrati sui proceeds sono stati ritirati: il ritiro avviene una volta sola), `labelledRows` (i basket del dataset, cioè etichettati e con le feature d'ingresso, ricontati dal ledger all'avvio dopo la verifica del realizzato e a ogni ciclo), `recentPAt` = `entry`, `recent` (ultime 200 coppie `{p, label}` con la p **all'ingresso**), `aucHistory` (`{utc, auc100}`, al più 300 punti), `entries` (per `basket_id` dei basket aperti: `f` = le 28 feature, `p` = la p all'ingresso, `utc`, e dalla revisione della 5.1 `z`, `c`, `b` = valori standardizzati, contributi e intercetta del modello che ha dato quella p, così la pagina la spiega anche dopo un riavvio), `lastProposal` (ultima proposta del bandit: `utc`, `context`, `preset`, `explored`, `means`, `text`) |
|
||||
| `ritirati/<utc>-etichette-proceeds/` | i modelli addestrati sulle etichette dei proceeds della 4.0.0-5.0.0, messi da parte una volta sola (tutto o niente) |
|
||||
|
||||
## `knowledge/preregistrazione.csv`
|
||||
|
||||
@@ -120,4 +170,4 @@ Una riga per forward test: `data;config_hash;modalita;durata_minima;n_minimo_bas
|
||||
|
||||
## `knowledge/models_registry.csv`, `knowledge/forward_registry.csv`
|
||||
|
||||
`versione;data;tipo;n_train;auc_wf;brier;logloss;stato;motivazione` (stato ∈ shadow, challenger, champion, ritirato) e `data;config_hash;modalita;basket;pnl_net;sharpe;dd;stato;motivazione`.
|
||||
`versione;data;tipo;n_train;auc_wf;brier;logloss;stato;motivazione` (stato ∈ shadow, challenger, champion, ritirato, rifatta — la logistica riaddestrata da sola sulle etichette corrette dopo che un avvio sull'altro conto ha corretto righe della 4.0-5.0) e `data;config_hash;modalita;basket;pnl_net;sharpe;dd;stato;motivazione`.
|
||||
@@ -1,8 +1,8 @@
|
||||
# Apprendimento: livelli 0-3
|
||||
|
||||
Aggiornato: 2026-09-23 (ADR-0006, 5.0). Tutto è costruito da zero nel Core (`src/Encelado.Core/Baskets/Learning/`), senza pacchetti: regressione logistica online, un MLP a 16 unità ReLU con Adam, un bandit di Thompson, due previsori di volatilità. Il codice del motore che li usa a runtime è `src/Encelado.Engine/Baskets/LearningState.cs`; lo stesso ciclo gira offline con `backtest learn`.
|
||||
Aggiornato: 2026-10-01 (5.1: pagina Apprendimento, ciclo in background con un solo scrittore, correzioni della revisione; ADR-0006 per lo stato in ombra, ADR-0014 per il ciclo). Tutto è costruito da zero nel Core (`src/Encelado.Core/Baskets/Learning/`), senza pacchetti: regressione logistica online, un MLP a 16 unità ReLU con Adam, un bandit di Thompson, due previsori di volatilità. Il codice del motore che li usa a runtime è `src/Encelado.Engine/Baskets/LearningState.cs` (stato e file), `LearningCycle.cs` (il ciclo), `LearningDataset.cs` (il dataset dal ledger), `LearningDiskReader.cs` (la pagina a motore fermo) e `BasketEngine.Learning.cs` (pubblicazione e comando); lo stesso ciclo gira offline con `backtest learn`.
|
||||
|
||||
**Regola che governa tutto**: nessun livello cambia un parametro live da solo. Il meta-modello può soltanto *rifiutare* un ingresso quando è attivo; il bandit *propone* un preset e **non lo applica** (dalla 5.0; fino alla 4.0.0 lo applicava in Paper e Demo); tutto il resto finisce in `knowledge/proposals.csv` e passa dal forward test pre-registrato.
|
||||
**Regola che governa tutto**: nessun livello cambia un parametro live da solo. Il meta-modello può soltanto *rifiutare* un ingresso quando è attivo **e** l'operatore ha acceso `learning.enabled`; il bandit *propone* un preset e **non lo applica** (dalla 5.0; fino alla 4.0.0 lo applicava in Paper e Demo); tutto il resto finisce in `knowledge/proposals.csv` e passa dal forward test pre-registrato.
|
||||
|
||||
## Stato dalla 5.0 (ADR-0006): quasi tutto in ombra
|
||||
|
||||
@@ -11,59 +11,82 @@ Aggiornato: 2026-09-23 (ADR-0006, 5.0). Tutto è costruito da zero nel Core (`sr
|
||||
| Componente | Runtime |
|
||||
|---|---|
|
||||
| Ledger, `orders.jsonl`, `baskets.csv` | scritti sempre: sono il dato |
|
||||
| Livello 0 (calibrazione) | generato dal ciclo, quindi fermo finché il ciclo non gira (`backtest learn`, o «Esegui ciclo di apprendimento» in Impostazioni ▸ Ricerca) |
|
||||
| Livello 0 (calibrazione) | generato dal ciclo, quindi fermo finché il ciclo non gira («Esegui ciclo» nella pagina Apprendimento, o `backtest learn`) |
|
||||
| Previsione di volatilità | attiva, deterministica, usata da `z_in` effettivo |
|
||||
| Logistica (livello 1) | **in ombra**: `p_ML` a ogni chiusura di barra nel ledger, apprendimento a ogni chiusura di basket; mai un cancello (`mlActive = false`) |
|
||||
| MLP challenger (livello 2) | non addestrato |
|
||||
| Bandit (livello 3) | riceve i premi e **propone** nel log; non applica |
|
||||
| Ciclo settimanale | non gira nel bot; passa a `backtest learn` o al pulsante di Impostazioni ▸ Ricerca |
|
||||
| Logistica (livello 1) | **in ombra**: `p_ML` a ogni chiusura di barra nel ledger, apprendimento a ogni chiusura di basket confermata dallo storico eToro; mai un cancello (`mlActive = false`) |
|
||||
| MLP challenger (livello 2) | non addestrato né aggiornato (serve `enabled` **e** `challenger`) |
|
||||
| Bandit (livello 3) | riceve i premi e **propone** nel log e nella pagina; non applica |
|
||||
| Ciclo settimanale | non gira nel bot; «Esegui ciclo» o `backtest learn` |
|
||||
|
||||
**Criterio di riattivazione** (`learning.enabled = true`, scritto dall'operatore, mai dal bot): almeno **300 basket chiusi in Demo** *e* **P&L netto forward ≥ 0** sulla metrica pre-registrata in `knowledge/preregistrazione.csv`. Prima di allora qualunque «adattamento automatico» è rumore: il meta-modello può solo ridurre le perdite di una strategia che il backtest dice non reggere i costi, e a poche entrate al giorno i 300 basket sono mesi. Motivazione completa in `docs/adr/ADR-0006-apprendimento-in-ombra.md`.
|
||||
**Criterio di riattivazione** (`learning.enabled = true`, scritto dall'operatore, mai dal bot): almeno **300 basket chiusi in Demo** *e* **P&L netto forward ≥ 0** sulla metrica pre-registrata in `knowledge/preregistrazione.csv` (il risultato del forward test va in `knowledge/forward_registry.csv`, che la pagina legge). Prima di allora qualunque «adattamento automatico» è rumore: il meta-modello può solo ridurre le perdite di una strategia che il backtest dice non reggere i costi, e a poche entrate al giorno i 300 basket sono mesi. Motivazione completa in `docs/adr/ADR-0006-apprendimento-in-ombra.md`.
|
||||
|
||||
Il cancello `ml_gate` filtra un ingresso solo se `learning.enabled` è acceso, l'attivazione dell'ultimo ciclo è superata e la `p_ML` esiste (`MlGate.IsActive`): dalla 5.1 vale anche nella seconda valutazione, quella che il motore rifà dopo aver riletto il conto prima di inviare l'ordine (nella 5.0 lì mancava il controllo di `enabled`).
|
||||
|
||||
## Il dataset
|
||||
|
||||
Una riga per basket **aperto**: le 28 feature scritte nel ledger nel momento della decisione (`decisions.jsonl`, evento `ingresso`), unite per `basket_id` all'esito scritto alla chiusura (`baskets.csv`: `label` = 1 se il P&L netto è positivo, `pnl_net`). Le feature non vengono mai ricostruite a posteriori: il dataset è il ledger (`LearningState.BuildDataset`).
|
||||
Una riga per basket **chiuso con il P&L stabilito dallo storico eToro** (`netProfit − fees`, lettore corretto di `baskets.csv`: le stime e le righe non verificabili non hanno etichetta; le gambe singole non sono basket): le 28 feature scritte nel ledger nel momento della decisione (`decisions.jsonl`, evento `ingresso`), unite per `basket_id` all'esito (`label` = 1 se il P&L netto è positivo). Le feature non vengono mai ricostruite a posteriori: il dataset è il ledger (`LearningDataset.Build`).
|
||||
|
||||
| # | Feature | Origine |
|
||||
|---|---|---|
|
||||
| 0-3 | `z`, `abs_z`, `z_in_eff`, `d_pips` | z-score del cross sintetico, soglia effettiva dopo la scala di volatilità, divergenza in pip |
|
||||
| 4-6 | `rho_w`, `rho_20`, `half_life` | correlazione rolling (finestra W e 20 barre), semiperiodo OLS |
|
||||
| 7-10 | `atr_a`, `atr_b`, `sigma_x`, `ewma_vol_x` | volatilità delle gambe e del cross |
|
||||
| 11 | `trend_strength` | forza di trend (ADX-like) del cross |
|
||||
| 12-15 | `spread_a`, `spread_b`, `cost_pips`, `break_even_win_rate` | costi del momento |
|
||||
| 16-18 | `hour_sin`, `hour_cos`, `day_of_week` | ora UTC ciclica, giorno |
|
||||
| 19-20 | `minutes_to_high`, `minutes_since_high` | calendario (troncati a 24 h) |
|
||||
| 21-23 | `sent_1h`, `sent_4h`, `hawkish_diff` | sentiment (valuta lunga − valuta corta del cross) |
|
||||
| 24 | `risk_off` | sentiment risk-off |
|
||||
| 25 | `vol_ratio` | σ prevista / σ media 30 giorni |
|
||||
| 26 | `last_outcomes` | media degli ultimi 10 esiti |
|
||||
| 27 | `buy_cross` | direzione |
|
||||
Dalla 5.1 una nota `ingresso` **senza feature** (un ingresso completato dopo una gamba in attesa, scritto dalla 5.0 come nota) **non è una riga di addestramento**: prima diventava un vettore di valori di default, cioè inventato. La pagina le conta (`entryRowsWithoutFeatures`). Le note `ingresso` della 5.1 portano il vettore della decisione che ha aperto il basket (array `features`) e la sua `p_ML`, quindi restano utilizzabili.
|
||||
|
||||
I nomi sono in `LearningFeatures.Names`; il test `LeakTests` verifica che nessun nome contenga l'esito e che un'etichetta presa dal futuro non sia apprendibile (AUC ≈ 0,5).
|
||||
`lastNOutcomes` delle righe scritte prima della marca `feature_inaffidabile` (le etichette della 4.0-5.0 erano i proceeds della chiusura) vale 0,5, il valore neutro. La marca si scrive al primo avvio che trova righe della 4.0-5.0 corrette, e di nuovo, con un `fino_a` più recente, quando un avvio sull'altro conto ne corregge altre dopo il ritiro (le righe di quel conto si verificano solo quando gira; nel frattempo `lastNOutcomes` era calcolata anche con quelle etichette): quell'avvio rifà anche la sola logistica sulle etichette corrette (`LearningState.ReplayLogistic`, riga `rifatta` in `models_registry.csv`), lasciando bandit, sfidante e ritiro come sono; dopo la verifica del realizzato all'avvio il motore rilegge dal ledger corretto gli esiti su cui calcola `lastNOutcomes` (e il conteggio dei basket etichettati) **anche se il ritiro dei modelli fallisce** (`LearningState.Reseed`), così le righe di valutazione scritte da quel momento portano un valore giusto.
|
||||
|
||||
**Il ritiro dei modelli** addestrati sui proceeds (ADR-0011) è tutto o niente: prima si leggono il dataset e gli esiti e si spostano i file in `data/models/ritirati/<utc>-etichette-proceeds/`; un errore lì lascia i modelli come sono, in memoria e su disco, e il ritiro si ritenta al prossimo avvio. Solo dopo vengono sostituiti i modelli (logistica riaddestrata sulle etichette corrette, bandit dal prior) e salvato `labelsFixedUtc`: il ritiro non si ripete mai sopra le ricompense imparate dopo, anche se la riga di `models_registry.csv` non si è potuta scrivere (resta un avviso nel log).
|
||||
|
||||
**Basket etichettati**: in ogni posto (tick, pagina, `learning_state.json`) sono quelli del dataset, cioè etichettati **e** con le feature d'ingresso; si ricontano dal ledger all'avvio dopo la verifica del realizzato e a ogni ciclo, e crescono di uno a ogni chiusura il cui ingresso il motore ricordava.
|
||||
|
||||
Il vettore, nell'ordine di `LearningFeatures.Names` (le etichette italiane sono in `LearningFeatures.Labels` e la pagina le mostra):
|
||||
|
||||
| # | Feature | Etichetta | Origine |
|
||||
|---|---|---|---|
|
||||
| 0 | `z` | z-score del cross | valutazione |
|
||||
| 1 | `abs_z` | \|z\| | valutazione |
|
||||
| 2 | `rho_W` | correlazione ρ sulla finestra | valutazione (finestra W) |
|
||||
| 3 | `rho_20` | correlazione ρ su 20 barre | valutazione |
|
||||
| 4 | `halfLife` | emivita (barre) | OLS sul cross (96 se ignota) |
|
||||
| 5-6 | `atrA`, `atrB` | ATR gamba A / B (pip) | barre delle gambe |
|
||||
| 7 | `sigmaX` | deviazione standard del cross | valutazione |
|
||||
| 8 | `ewmaVolX` | volatilità EWMA del cross | valutazione |
|
||||
| 9 | `regimeTrend` | forza del trend (tipo ADX) | cross sintetico (20 se ignota) |
|
||||
| 10 | `costPips` | costo stimato (pip) | cost gate |
|
||||
| 11-12 | `spreadA`, `spreadB` | spread gamba A / B (pip) | quotazioni |
|
||||
| 13-14 | `hourSin`, `hourCos` | ora del giorno (seno / coseno) | orologio UTC |
|
||||
| 15 | `dow` | giorno della settimana | orologio UTC |
|
||||
| 16 | `minutesToNextHigh` | minuti al prossimo evento ad alto impatto | calendario (troncati a 1440) |
|
||||
| 17 | `minutesSinceLastHigh` | minuti dall'ultimo evento ad alto impatto | calendario (troncati a 1440) |
|
||||
| 18 | `surpriseLast` | sorpresa dell'ultimo dato | calendario |
|
||||
| 19-21 | `netSentDiff_1h`, `_4h`, `_24h` | differenza di sentiment 1 h / 4 h / 24 h | notizie (valuta lunga − corta del cross) |
|
||||
| 22 | `hawkishDiff` | differenza hawkish | notizie |
|
||||
| 23 | `riskOff` | risk-off | notizie |
|
||||
| 24 | `newsCount` | notizie nelle ultime 24 h | notizie |
|
||||
| 25 | `volRatio` | volatilità prevista / media 30 g | previsore di volatilità (1 se ignota) |
|
||||
| 26 | `lastNOutcomes` | esito medio degli ultimi 10 basket | etichette (0,5 se ignoto o mascherato) |
|
||||
| 27 | `buy_cross` | acquisto del cross | decisione |
|
||||
|
||||
Il test `LeakTests` verifica che nessun nome contenga l'esito e che un'etichetta presa dal futuro non sia apprendibile (AUC ≈ 0,5).
|
||||
|
||||
## Livello 0 — Calibrazione
|
||||
|
||||
`CalibrationTables.Build` raggruppa i basket chiusi per basket, preset, terzile di volatilità, ora del giorno, bucket di |z| e di costo, e scrive win rate e P&L medio per bucket in `knowledge/calibration.csv` (colonna `motivazione` con il conteggio). Serve a leggere dove la strategia paga e dove no, e a niente altro: non cambia soglie.
|
||||
`CalibrationTables.Build` raggruppa i basket del dataset per nove dimensioni — `abs_z` (soglie 1,5 / 2 / 2,5 / 3), `rho_W` (−0,9 / −0,8 / −0,7 / −0,6 / 0), `ora_utc`, `giorno`, `minuti_evento` (60 / 180 / 720), `sentiment_4h` (±0,05 / ±0,2), `preset`, `basket`, `verso` — e scrive conteggio, win rate, P&L medio e totale per bucket in `knowledge/calibration.csv` (colonna `motivazione`: «campione piccolo» sotto 20, «bucket in utile» o «in perdita»). Serve a leggere dove la strategia paga e dove no, e a niente altro: non cambia soglie.
|
||||
|
||||
## Livello 1 — Logistica online (il campione)
|
||||
|
||||
`OnlineLogistic`: pesi su 28 feature standardizzate con statistiche rolling (`RollingStandardizer`, emivita 200 righe), SGD con L2 = 10⁻³ e tasso 0,01/√(1+n/100). Predice a ogni chiusura di barra (`p_ML` nella dashboard, "in ombra") e impara a ogni chiusura di basket. Stato in `data/models/logreg_current.json`; versioni datate `logreg_vN.json` con `trained_on_until` e hash del dataset.
|
||||
`OnlineLogistic`: pesi su 28 feature standardizzate con statistiche rolling (`RollingStandardizer`, emivita 200 righe, valori tagliati a ±5), SGD con L2 = 10⁻³ e tasso **lr₀ / (1 + n/1000)** con lr₀ = 0,01. Predice a ogni chiusura di barra a basket piatto (`p_ML`, "in ombra") e impara a ogni chiusura di basket confermata dallo storico. Stato in `data/models/logreg_current.json`; versioni datate `logreg_vN.json` con `trained_on_until`, righe, hash del dataset e origine del ciclo. I pesi agiscono su feature standardizzate: |w| ordina l'importanza e il contributo di una feature alla previsione è `w·z`. La pagina mostra i contributi **del modello che ha dato quella `p_ML`**: il motore li prende insieme alla p a ogni chiusura di barra a basket piatto (una sola lettura sotto il lock dello stato, `LearningState.Score`) e li conserva con l'ingresso, anche in `learning_state.json`, così sopravvivono a un riavvio; la loro somma più l'`intercept` della riga è il logit di `p_ML`. Una p senza una spiegazione conservata (la p all'ingresso di un basket aperto prima della 5.1 quando il modello nel frattempo è cambiato, o la p del campione MLP) è mostrata senza contributi: mai spiegata con un modello che non l'ha data.
|
||||
|
||||
**Valutazione walk-forward** (`ModelEvaluator.EvaluateLogistic`): sequenziale, predici-poi-aggiorna, con i primi 30 basket di burn-in esclusi dalle metriche. Metriche: AUC con intervallo bootstrap (1000 ricampionamenti), Brier, log-loss, curva di calibrazione in 10 bin, P&L di tutti i basket contro P&L dei soli basket con p ≥ `mlMinProbability`, Sharpe e DSR del filtrato.
|
||||
|
||||
**Attivazione** (§8.3 della specifica), tutte insieme:
|
||||
|
||||
1. almeno **300** basket chiusi;
|
||||
1. almeno **300** basket nel dataset;
|
||||
2. AUC walk-forward ≥ **0,55** con l'intervallo bootstrap che esclude 0,50;
|
||||
3. P&L filtrato migliore del P&L non filtrato **e** DSR del filtrato ≥ **0,95**.
|
||||
|
||||
Quando è attivo, un ingresso con p < `mlMinProbability` (0,55) viene rifiutato (`ml_gate` nel ledger). **Disattivazione**: se l'AUC mobile sugli ultimi 100 basket scende sotto **0,52** il modello torna in ombra e lo scrive in `models_registry.csv`.
|
||||
Quando è attivo (e `learning.enabled` è acceso), un ingresso con p < `mlMinProbability` (0,55) viene rifiutato (`ml_gate` nel ledger). **Disattivazione**: se l'AUC mobile sugli ultimi 100 basket scende sotto **0,52** il modello torna in ombra e lo scrive in `models_registry.csv`.
|
||||
|
||||
Stato del 2026-09-16: **0 basket chiusi nel ledger** → il modello è in ombra e non è valutabile. Nessuna cifra qui è un risultato.
|
||||
**AUC mobile (5.1)**: le coppie (p, esito) sono la probabilità data **all'ingresso** di ciascun basket — salvata con le sue feature quando il basket apre — e l'esito alla chiusura. Fino alla 5.0 la p veniva ricalcolata alla chiusura da un modello che nel frattempo aveva già imparato dai basket chiusi durante la vita di quello: un'AUC ottimista, non confrontabile con il walk-forward. Le coppie della 5.0 vengono scartate alla prima lettura. Dopo ogni ciclo le coppie ripartono dalle p all'ingresso del walk-forward (dopo il burn-in), le stesse su cui si calcola l'AUC del ciclo.
|
||||
|
||||
## Livello 2 — MLP challenger
|
||||
|
||||
`SmallMlp`: 28 → 16 ReLU → 1 sigmoide, inizializzazione Glorot con seme fisso, Adam (β 0,9/0,999), L2 = 10⁻⁴, mini-batch 8-64. Addestrato dal ciclo settimanale in **5 fold cronologici con purga ed embargo di 24 ore** attorno al fold di test, **5 semi** mediati, early stopping sull'ultimo 20 % (cronologico) dei dati di addestramento con pazienza 20 epoche. Lo standardizzatore viene adattato all'intero insieme di addestramento prima del fit (le statistiche rolling partono da zero e distorcono le prime righe: scoperto e corretto con il test sul cerchio, vedi `ModelTests`).
|
||||
`SmallMlp`: 28 → 16 ReLU → 1 sigmoide, inizializzazione Glorot con seme fisso, Adam (β 0,9/0,999), L2 = 10⁻⁴, mini-batch 8-64, tasso 0,003 nell'addestramento del ciclo e 0,001 nell'aggiornamento online. Addestrato dal ciclo **solo con `learning.enabled` e `learning.challenger` accesi** (dalla 5.1: prima veniva addestrato comunque) in **5 fold cronologici con purga ed embargo di 24 ore** attorno al fold di test, **5 semi** mediati, early stopping sull'ultimo 20 % (cronologico) dei dati di addestramento con pazienza 20 epoche; servono almeno 60 basket. Lo standardizzatore viene adattato all'intero insieme di addestramento prima del fit (le statistiche rolling partono da zero e distorcono le prime righe: scoperto e corretto con il test sul cerchio, vedi `ModelTests`). Con il challenger spento il ciclo non lo addestra, il motore non lo aggiorna e `mlp_current.json` viene tolto (le versioni `mlp_vN.json` restano).
|
||||
|
||||
Il **gradient check** (`SmallMlp.GradientCheck`, test `TheMlpGradientMatchesTheNumericalOne`) confronta il gradiente analitico di ogni peso vivo del primo strato con la differenza centrale numerica: scarto relativo < 10⁻⁴.
|
||||
|
||||
@@ -71,33 +94,76 @@ Promozione a campione: solo se batte la logistica di almeno 0,01 di AUC walk-for
|
||||
|
||||
## Livello 3 — Bandit sui preset
|
||||
|
||||
`ThompsonBandit`: una Beta(α, β) per braccio = preset × terzile di volatilità prevista (3 × 3). A ogni chiusura il braccio usato riceve 1 se il basket è positivo. La proposta campiona dalle posteriori con un **tetto del 10 %** alle scelte esplorative (`ExplorationCap`; test `TheBanditKeepsExplorationUnderTheCap`). Dalla 5.0 la proposta viene scritta nel log e in `knowledge/proposals.csv` e **non viene applicata** in nessuna modalità (D-30); fino alla 4.0.0 in Paper e Demo cambiava il preset a caldo.
|
||||
`ThompsonBandit`: una Beta(α, β) per braccio = preset × terzile di volatilità prevista (3 × 3, prior Beta(1, 1)). Il terzile è quello della σ prevista alla chiusura rispetto alle σ delle chiusure precedenti (contesto «vol media» finché le chiusure sono meno di 9). A ogni chiusura confermata dallo storico il braccio **del preset con cui il basket è entrato** (salvato nel basket e nella sua riga di `baskets.csv`; fino alla prima 5.1 era il preset in vigore alla chiusura) riceve 1 se il basket è positivo; `byPreset` del dataset e la dimensione `preset` della calibrazione leggono la stessa colonna. La proposta è golosa sulla media a posteriori, salvo un **tetto del 10 %** di scelte campionate (esplorative; `ExplorationCap`, test `TheBanditKeepsExplorationUnderTheCap`). Dalla 5.0 la proposta viene scritta nel log e mostrata nella pagina e **non viene applicata** in nessuna modalità (D-30); dalla 5.1 l'ultima proposta (contesto, preset, medie, se esplorativa) viene salvata e sopravvive a un riavvio. La pagina mostra per ogni braccio α, β, vittorie, sconfitte, media e intervallo di credibilità al 95 % (quantili della Beta), e in oro il migliore del suo contesto: la media a posteriori più alta, **solo per un braccio provato almeno una volta** (n > 0). Un bandit nuovo non ha bracci migliori, e nemmeno un contesto i cui bracci provati non fanno meglio del prior; a pari media vince il primo nell'ordine Conservative, Moderate, Aggressive.
|
||||
|
||||
## Previsione della volatilità
|
||||
|
||||
`VolForecaster`: sui rendimenti a 15 minuti del cross calcola la varianza realizzata giornaliera e mantiene due previsori a 1-4 ore, **EWMA** (span 100) e **HAR-RV** (OLS sulle medie a 1, 5 e 22 giorni, rifittato ogni giorno). Ogni giorno confronta l'errore quadratico delle due previsioni sulla finestra mobile e usa quello migliore (`ActiveModel`). Il rapporto σ prevista / σ media 30 giorni scala la soglia `z_in` (`volScaleZIn`) e la size, ed è la feature `vol_ratio`.
|
||||
`VolForecaster`, uno per basket: sui rendimenti logaritmici a 15 minuti del cross sintetico tiene la varianza realizzata di barra (ultime 20 000 barre) e due previsori per le prossime 8 barre (2 ore): **EWMA** (span 100) e **HAR-RV** (OLS della varianza della barra successiva sulle medie a **15 minuti, 4 ore e 24 ore**, cioè 1, 16 e 96 barre; rifittato una volta al giorno dopo 480 barre, su al più 5 760 righe e almeno 200). Ogni previsione viene confrontata con la volatilità realizzata nelle 8 barre successive; con almeno 50 confronti si usa il modello con l'errore quadratico minore (`ActiveModel`). Il rapporto σ prevista / σ media 30 giorni scala la soglia `z_in` (entro `volScaleMin`–`volScaleMax`, 0,8–1,5) ed è la feature `volRatio`.
|
||||
|
||||
Dalla 5.1 si mette in coda **al più una previsione per barra**: il motore chiede la previsione anche a ogni lettura delle quotazioni di un basket aperto (ogni pochi secondi) e la 5.0 le accodava tutte, con una coda che cresceva senza limite e confronti fatti su previsioni vecchie di ore. `Stats()` e `Describe()` sono letture pure: non accodano niente e non cambiano il modello in uso.
|
||||
|
||||
## Deriva
|
||||
|
||||
L'indice di stabilità (PSI) previsto dalla specifica non è collegato a niente: il codice è stato rimosso nella pulizia della 5.0 (era una classe mai chiamata). Quando il meta-modello sarà attivabile, il controllo della deriva va reintrodotto insieme al criterio di ritorno in ombra, non prima.
|
||||
|
||||
## Ciclo settimanale e comando `learn`
|
||||
## Il ciclo
|
||||
|
||||
`LearningState.RunCycle` — nel bot solo con `learning.weeklyCycle = true` (la domenica dopo le 10 UTC o al primo avvio dopo sette giorni); altrimenti a mano, dallo strumento o dall'interfaccia:
|
||||
Il ciclo (§8.7) ricostruisce il dataset dal ledger, valuta e riaddestra la logistica (walk-forward) e — se acceso — il challenger (fold purgati), e scrive la base di conoscenza. Dalla 5.1 è una **funzione pura in background** (`LearningCycle.Train`): legge solo il ledger, in condivisione, senza esserne lo scrittore, e restituisce tutto senza toccare niente; il thread di decisione lo **applica** fra due tick in pochi millisecondi (`LearningState.Apply`): sostituisce i modelli, rigioca sui nuovi modelli i basket chiusi mentre il ciclo si addestrava, aumenta la versione, scrive ogni file intero. Il motore intanto continua a lavorare (nella 5.0 l'addestramento girava sul thread di decisione con il lock dell'apprendimento preso: quotazioni e uscite ferme per tutta la durata). Il ciclo si interrompe fra un fold, un seme o un'epoca e l'altro quando il motore si ferma.
|
||||
|
||||
Fasi mostrate nella pagina: `dataset`, `logistica`, `mlp`, `scrittura`.
|
||||
|
||||
**Quando gira**:
|
||||
|
||||
- **settimanale nel bot**: solo con `learning.enabled` e `learning.weeklyCycle` accesi, la domenica dalle 10:00 UTC, quando sono passati almeno sette giorni dal precedente (qualunque sia stato); stesso percorso in background; un ciclo fallito si ritenta non prima di un'ora;
|
||||
- **«Esegui ciclo»** nella pagina Apprendimento (`POST /api/commands/learn`), in ogni stato:
|
||||
- motore in esecuzione: il comando va al motore, che avvia il ciclo e risponde subito; l'avanzamento è in `schedule.running` / `runningPhase`;
|
||||
- motore fermo o in errore: **manutenzione a motore fermo** — il server prende il lock di istanza della cartella dati (un solo scrittore di `data/models` e `knowledge` alla volta), addestra in background e applica; **AVVIA risponde 409** (`code: refused`) finché dura, di solito pochi secondi;
|
||||
- un ciclo già in corso, un motore che si sta avviando o fermando, o un altro processo che tiene il lock: rifiutato (409, `code: refused`) con il motivo;
|
||||
- **`backtest learn`** (strumento): prende anch'esso il lock di istanza della cartella dati, o si rifiuta con il nome di chi lo tiene: con il bot acceso si usa «Esegui ciclo».
|
||||
|
||||
```powershell
|
||||
dotnet run --project tools/Encelado.Backtest -- learn --data <cartella data del bot> [--knowledge <cartella>] [--strategy config/strategy.json]
|
||||
dotnet msbuild build/Release.proj -t:Backtest -p:Dati="%USERPROFILE%\Documents\Encelado\data" -p:Comando=learn
|
||||
```
|
||||
|
||||
`--data` è la cartella che contiene `ledger/` (una copia di `/data/data` del container va benissimo); `--knowledge` è dove scrivere (default: `knowledge` accanto ai dati). Lo strumento stampa quante righe ha il dataset e lo stato del modello dopo il ciclo. Il pulsante «Esegui ciclo di apprendimento» in Impostazioni ▸ Ricerca fa la stessa cosa sui dati del container. Il ciclo:
|
||||
`--data` è la cartella che contiene `ledger/` (una copia di `/data/data` del container va benissimo); `--knowledge` è dove scrivere (default: `knowledge` accanto ai dati). Lo strumento stampa quante righe ha il dataset, la versione e lo stato del modello dopo il ciclo e i file che ha scritto (`logreg_current.json`, `logreg_vN.json`, `last_cycle.json`, `learning_state.json`; `calibration.csv`, `insights_AAAASS.md`, `models_registry.csv`, `proposals.csv`).
|
||||
|
||||
1. ricostruisce il dataset dal ledger;
|
||||
2. valuta e riaddestra logistica (walk-forward) e MLP (fold purgati);
|
||||
3. scrive `knowledge/calibration.csv`, `knowledge/insights_YYYYWW.md` (cosa ha funzionato, calibrazione, meta-modello, bandit, parametri suggeriti), `knowledge/models_registry.csv`, `knowledge/proposals.csv` (una riga per proposta, con evidenza e stato `proposta`);
|
||||
4. salva i modelli con versione.
|
||||
**Cosa scrive un ciclo**:
|
||||
|
||||
**Le proposte non toccano niente.** Il percorso per cambiare un parametro live è: proposta → `knowledge/preregistrazione.csv` (metrica, soglia, periodo, N minimo, scritti prima) → forward test in Paper/Demo → `forward_registry.csv` → decisione umana.
|
||||
1. `data/models/logreg_vN.json` (e `mlp_vN.json` con il challenger) con `trained_on_until`, `trained_at`, righe, hash del dataset, origine e nomi delle feature;
|
||||
2. `data/models/last_cycle.json`: la valutazione completa del ciclo (AUC con intervallo, Brier, log-loss, calibrazione, P&L di tutti e filtrati, Sharpe, DSR, attivazione e motivazione, per la logistica e il challenger) e il riepilogo del dataset — fino alla 5.0 tutto questo veniva calcolato e buttato via, restava solo una riga di testo;
|
||||
3. `knowledge/calibration.csv`, `knowledge/insights_AAAASS.md` (con l'anno della **settimana ISO**: nei primi giorni di gennaio la settimana 52 o 53 appartiene all'anno prima, e la 5.0 sbagliava l'anno), righe in `knowledge/models_registry.csv` e `knowledge/proposals.csv` (una riga per proposta, con evidenza e stato `proposta`).
|
||||
|
||||
**Le proposte non toccano niente.** Il percorso per cambiare un parametro live è: proposta → `knowledge/preregistrazione.csv` (metrica, soglia, periodo, N minimo, scritti prima) → forward test in Demo → `forward_registry.csv` → decisione umana.
|
||||
|
||||
## La pagina Apprendimento (`GET /api/learning`, 5.1)
|
||||
|
||||
La pagina raccoglie tutto ciò che il sistema sa dell'apprendimento; la forma esatta dei campi è in `docs/API.md`. Sezioni:
|
||||
|
||||
- **stato**: modalità (`ombra-disabilitato`, `ombra`, `attivo`), interruttori, attivazione, versione, basket appresi, soglia `p`, perché è in questo stato, ingressi in attesa di esito;
|
||||
- **dataset**: righe di `baskets.csv`, basket etichettati, senza riga d'ingresso, con l'ingresso senza feature, gambe singole, righe corrette e non verificate, vinti e persi, P&L netto (totale, medio, mediano, 5° percentile), per modalità, basket, preset e motivo d'uscita, avanzamento verso i 300, **etichette sospette** (win rate ≥ 90 % su 20 basket o più, un basket con P&L oltre il 5 % dell'equity all'ingresso, segno del P&L in contrasto con i pip netti in più di un quinto dei casi chiari: i sintomi dei proceeds della 4.0-5.0);
|
||||
- **attivazione**: ogni condizione con valore attuale, richiesta ed esito (`null` = non valutabile): righe, AUC, estremo dell'intervallo, P&L filtrato, DSR, chiusi in Demo, P&L forward, interruttore dell'operatore, AUC mobile mentre è attivo;
|
||||
- **logistica**: iperparametri, tasso attuale, pesi per |w| con media e deviazione standard dello standardizzatore; **challenger** (se c'è);
|
||||
- **ultimo ciclo**: la valutazione di `last_cycle.json`;
|
||||
- **AUC mobile**: AUC su 100 e 200, intervallo bootstrap, Brier, log-loss, win rate e p media degli ultimi 100, media degli ultimi 10 esiti, le coppie (p all'ingresso, esito), l'AUC nel tempo, la calibrazione;
|
||||
- **basket**: per ciascuno `p_ML` con l'ora e il tipo — «ultima barra», «all'ingresso» (basket in posizione o in attesa di una gamba: le feature sono quelle dell'ingresso) o «ricalcolata con il modello di oggi» (motore fermo, basket piatto, e il modello salvato non ridà la p dell'ultima riga del ledger: la p mostrata è quella che il modello salvato dà ai valori di quella riga) —, se il filtro lo scarterebbe, i cinque contributi maggiori (`w·z`) con l'`intercept` del modello che ha dato la p, su richiesta (`?features=all`) il vettore completo, e il previsore di volatilità (modello in uso, σ EWMA / HAR / prevista / media 30 g, scala di `z_in`, errori, previsioni valutate e in coda, ultimo fit, terzile);
|
||||
- **bandit**: bracci, quota esplorativa, preset in uso (fisso), ultima proposta; **volatilità**: storico delle σ alle chiusure e soglie dei terzili;
|
||||
- **conoscenza**: calibrazione, ultime proposte (con `basedOnSuspectData` per quelle nate dalle etichette sbagliate) e righe del registro, l'insight più recente (al più 64 KB), i file dei modelli e di `knowledge/`;
|
||||
- **pianificazione**: ultimo ciclo, prossimo, se gira nel bot, se sta girando (da quando, in che fase), durata, errore e origine dell'ultimo;
|
||||
- **avvisi**: frasi per l'operatore.
|
||||
|
||||
**Da dove vengono i numeri**: a motore acceso il thread di decisione costruisce un rapporto immutabile e lo pubblica (a ogni chiusura di barra e di basket, dopo un ciclo e un comando, all'avvio e una volta al minuto): il web lo legge senza mai toccare lo stato del motore. A motore fermo lo stesso rapporto viene letto dai file in sola lettura (`LearningDiskReader`: nessuna cartella creata, file aperti in condivisione, righe a metà scartate, riletto solo quando i file cambiano). Un file dei modelli che non si riesce a leggere (modificato a mano, schema diverso, permessi) lascia **l'ultima lettura buona** di quella parte — logistica, MLP, bandit, stato, ultimo ciclo — e un avviso lo dice; se una lettura buona di quella parte non c'è mai stata, l'avviso dice che sono mostrati i valori iniziali, anche alle letture successive (una lettura buona di un'altra parte non conta). Un file assente vale i valori iniziali, senza avviso. La base di conoscenza e il dataset aggiornato si leggono sempre dal disco; il dataset si ricalcola quando cambia `baskets.csv`, quando compare un file delle decisioni, **appena il ledger riceve una correzione `pnl_realizzato` o la marca `feature_inaffidabile`** (lette in modo incrementale) e comunque al più ogni ora. La risposta ha un `ETag` (versione della sezione + impronta dei file letti, `strategy.json` compreso: da lì un motore fermo prende interruttori, soglia e basket); la pagina la rilegge quando cambia `versions.learning` nel tick — che avanza anche a ogni salvataggio di un campo della strategia — e riceve 304 se niente è cambiato. Il tick porta i numeri principali (`learning`: modalità, basket etichettati, AUC mobile, proposta del bandit, modello di volatilità, ciclo in corso, avvisi), presi dallo stesso rapporto: i basket etichettati del tick sono quelli del dataset della pagina.
|
||||
|
||||
## Correttezza dei file (5.1)
|
||||
|
||||
- **Un solo scrittore**: il motore costruisce lo stato dell'apprendimento solo dopo aver preso il lock di istanza e lo salva, sotto il suo lock, prima di rilasciarlo; un motore rifiutato dal lock non scrive niente. La manutenzione a motore fermo e `backtest learn` prendono lo stesso lock.
|
||||
- **File interi**: ogni file dei modelli e della conoscenza si scrive su un `.tmp` con nome unico e si rinomina (`AtomicFile`); la 5.0 scriveva i modelli direttamente, e un file troncato azzerava tutto alla lettura successiva.
|
||||
- **Ingressi salvati subito**: le feature e la p di un basket aperto finiscono in `learning_state.json` all'apertura, non alla chiusura successiva.
|
||||
- **Chiusure del broker**: un basket chiuso dagli stop nativi o a mano (`closed_by_broker`) insegna come gli altri quando lo storico ne conferma il P&L; se resta una stima il suo ingresso viene dimenticato (nella 5.0 restava in memoria per sempre).
|
||||
- **La p con la sua spiegazione** (revisione): con l'ingresso si salvano anche i valori standardizzati, i contributi e l'intercetta del modello che ha dato la p (`z`, `c`, `b` in `learning_state.json`); un basket aperto ripreso dopo un riavvio torna ad avere la sua p d'ingresso, nella pagina, nel tick e nelle righe nuove del ledger (`p_ML`, `p_ml_at_entry`). Questi dati servono a mostrare e a registrare: la p di un basket aperto non decide niente.
|
||||
- **Ritiro tutto o niente** e **riletture dal ledger corretto** dopo la verifica del realizzato: vedi «Il dataset».
|
||||
|
||||
**Limiti noti** (in `docs/KNOWN_ISSUES.md`): il vettore che il modello vivo valuta alla chiusura di barra ha `costPips` a 0 (il costo dell'ingresso non è ancora calcolato a quel punto), mentre la riga d'ingresso su cui il ciclo addestra ha il costo vero; e un ingresso completato dopo un riavvio a metà (gamba in attesa) non ha il vettore, quindi non diventa una riga di addestramento.
|
||||
|
||||
## Cosa è stato escluso, e perché
|
||||
|
||||
@@ -110,8 +176,10 @@ dotnet msbuild build/Release.proj -t:Backtest -p:Dati="%USERPROFILE%\Documents\E
|
||||
| File | Contenuto |
|
||||
|---|---|
|
||||
| `data/models/logreg_current.json`, `mlp_current.json`, `bandit.json` | stato corrente (ripreso all'avvio) |
|
||||
| `data/models/logreg_vN.json`, `mlp_vN.json` | versioni del ciclo settimanale con `trained_on_until`, righe, hash del dataset, nomi delle feature |
|
||||
| `data/models/learning_state.json` | attivo/ombra, campione, versione, ultimi 200 (p, esito) per l'AUC mobile, feature dei basket aperti |
|
||||
| `knowledge/calibration.csv`, `insights_YYYYWW.md`, `models_registry.csv`, `proposals.csv`, `forward_registry.csv`, `preregistrazione.csv` | vedi `docs/LEDGER_SCHEMA.md` |
|
||||
| `data/models/logreg_vN.json`, `mlp_vN.json` | versioni dei cicli con `trained_on_until`, `trained_at`, righe, hash del dataset, origine, nomi delle feature |
|
||||
| `data/models/last_cycle.json` | valutazione dell'ultimo ciclo e riepilogo del dataset (dalla 5.1) |
|
||||
| `data/models/learning_state.json` | schema 2: attivo/ombra, campione, versione, ultimo ciclo e suo esito, quando i modelli dei proceeds sono stati ritirati, basket etichettati (il conteggio del dataset), ultime 200 coppie (p all'ingresso, esito), AUC mobile nel tempo (300 punti), ingressi in attesa con feature, p e ora e, dalla revisione, valori standardizzati, contributi e intercetta della p (`z`, `c`, `b`), ultima proposta del bandit. Schema completo in `docs/LEDGER_SCHEMA.md` |
|
||||
| `data/models/ritirati/<utc>-etichette-proceeds/` | i modelli addestrati sulle etichette dei proceeds, messi da parte una volta sola dalla 5.1 (tutto o niente) |
|
||||
| `knowledge/calibration.csv`, `insights_AAAASS.md`, `models_registry.csv`, `proposals.csv`, `forward_registry.csv`, `preregistrazione.csv` | vedi `docs/LEDGER_SCHEMA.md` |
|
||||
|
||||
Test: `tests/Encelado.Tests/LearningTests.cs` (i: gradient check, apprendimento walk-forward, MLP contro logistica su una regola non lineare, bandit, volatilità; j: leak; l: blocchi).
|
||||
Test: `tests/Encelado.Tests/LearningTests.cs` (gradient check, apprendimento walk-forward, MLP contro logistica su una regola non lineare, bandit, volatilità, leak, blocchi) e `LearningReportTests.cs` (5.1: letture pure dei modelli, coda della volatilità, cancello, note senza feature, AUC mobile, dataset ed etichette sospette, attivazione, pianificazione, nome degli insight, stato salvato, ciclo in background e applicazione, challenger, lettore del disco, comando «Esegui ciclo» in ogni stato, `/api/learning` con i dati d'esempio e a motore fermo, `ETag` e 304) e `LearningReviewTests.cs` (revisione: contributi che spiegano la p mostrata, anche dopo un riavvio; ritiro tutto o niente; rilettura dal ledger corretto; conteggio dal dataset; ultima lettura buona a motore fermo; bracci mai provati).
|
||||
@@ -38,7 +38,7 @@ Ogni domanda è numerata per fase. Quando l'utente non ha risposto, è stato app
|
||||
| D-20 | Per il test lungo in demo: `DemoAuto` (bot autonomo) o `DemoApprove`? | DemoAuto | **Risposta dell'utente (2026-09-16 15:00)**: «tutti gli Approve devono sparire, almeno per il momento. Il bot deve girare in completa autonomia aprendo e chiudendo le posizioni senza il mio consenso». Modalità ridotte a `Paper`, `Demo`, `Live`; coda delle approvazioni rimossa (ADR-0005). Il Live conserva flag e frase `CONFERMO LIVE`. |
|
||||
| D-21 | La pulizia delle «vecchie gestioni» deve includere anche cTrader/proba e la pipeline di ricerca? | sì, tutto | **Risposta dell'utente**: «Tutto: resta solo eToro + basket». Rimossi `Encelado.CTrader`, `Encelado.Storage`, ricerca, indicatori, RL, TA-Lib e i test relativi (ADR-0004). |
|
||||
| D-22 | Versione del rilascio su Gitea? | 4.0.0 | **Risposta dell'utente**: 4.0.0 (nuovo broker, nuova strategia, configurazione incompatibile). |
|
||||
| D-23 | Fuso orario della finestra: quello del computer o selezionabile? | computer, selezionabile | **Applicato**: `ui.timeZone` = `computer` di fabbrica; elenco dei fusi di Windows in Impostazioni; `ENCELADO_TIME_ZONE` da ambiente. Solo la finestra cambia: il log porta l'offset, il ledger è UTC. |
|
||||
| D-23 | Fuso orario della finestra: quello del computer o selezionabile? | computer, selezionabile | **Applicato**: `ui.timeZone` = `computer` di fabbrica; elenco dei fusi di Windows in Impostazioni; `ENCELADO_TIME_ZONE` da ambiente. Solo la finestra cambia: il log porta l'offset, il ledger è UTC. **Superata in parte dalla 5.1** (D-49): gli orari a schermo sono nel fuso del browser, con gli orologi delle valute; `ui.timeZone` resta nel file solo per gli orari scritti dal server (riga di stato) e non compare più in Impostazioni; `ENCELADO_TIME_ZONE` viene ignorata. |
|
||||
| D-24 | L'endpoint dei costi restituiva markup e overnight a zero: era davvero zero? | verificare | **Verificato via API il 2026-09-16 12:45 UTC**: il campo si chiama `value`, non `amount`. EURUSD 10 000 unità leva 10: markup 0,0, spread di mercato 0,1 USD (0,1 pip), overnight 0,91 USD/giorno (≈ 0,9 pip/gamba/giorno). Parser corretto; aggiunto lo scenario di costi `api` al backtest. |
|
||||
| D-25 | Google News vieta `/rss/search` nel robots.txt: forzare, sostituire o omettere? | omettere | **Default applicato: omettere** (il bot rispetta il robots.txt). SNB e RBNZ restano senza fonte; documentato in `KNOWN_ISSUES.md`. |
|
||||
|
||||
@@ -53,10 +53,38 @@ Domande del prompt «Encelado 5.0» (§15) più quelle emerse dalla verifica. D-
|
||||
| D-28 | Confermi il ritiro del progetto WPF a favore della web UI servita dal bot? | sì (ADR-0007) | **Risposta dell'utente (2026-09-23)**: «Sì, confermo: il bot deve essere eseguito SOLO tramite container. Elimina tutta la parte della grafica Windows». Applicata: progetto WPF rimosso, `Encelado.Engine` + `Encelado.Server`, interfaccia web Material 3, chiavi in file cifrato al posto di DPAPI, VS Code con F5 sul server (ADR-0007, ADR-0008). |
|
||||
| D-29 | Registry per l'immagine e URL dell'icona del template Unraid? | Gitea (`build/gitea.example.json`), icona nel repo | **Risposta dell'utente (2026-09-23)**: «Per il registro useremo Gitea per il momento. L'icona non si può pubblicare da qualche parte su Gitea?». Applicata: immagine `192.168.30.23:3000/alby96/encelado:<versione>` sul registro dei container di Gitea (stesso token della release); icona `assets/encelado.png` servita da Gitea come file raw del repository (`Icon` del template). |
|
||||
| D-30 | Confermi la disattivazione a runtime di MLP, bandit e ciclo settimanale? | sì (ADR-0006) | **Default applicato** (ADR-0006, 2026-09-23): il bandit propone e non applica (Fase 1); `learning.enabled = false` di fabbrica spegne ciclo settimanale e challenger e impedisce al cancello ML di attivarsi; la logistica resta in ombra. Il comando `learn` dello strumento arriva con la Fase 6. Resta aperta solo se vuoi il contrario. |
|
||||
| D-31 | Token e chat ID Telegram via variabili d'ambiente? Comandi in ingresso o solo notifiche? | env; comandi attivi | **Default applicato** (Fase 5). |
|
||||
| D-32 | Le posizioni esterne vanno chiuse dal kill-switch di default? | no | **Default applicato**: `risk.closeForeignOnKill = false`; la conferma del kill-switch ha la spunta «chiudi anche le esterne», deselezionata. |
|
||||
| D-33 | Valute del selettore oltre USD/EUR? | USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD | **Default applicato** (Fase 7). Per GBP e JPY il polling aggiunge GBPUSD e USDJPY. |
|
||||
| D-31 | Token e chat ID Telegram via variabili d'ambiente? Comandi in ingresso o solo notifiche? | env; comandi attivi | **Default applicato** (Fase 5). **Superata dalla 5.1** (2026-09-30, D-48, ADR-0010): il token del bot si inserisce da Impostazioni ▸ Notifiche Telegram, viene verificato con `getMe` e vive cifrato in `secrets.enc`; la chat (`notifications.telegram.chatId`) si imposta nella stessa pagina. `TELEGRAM_BOT_TOKEN` e `TELEGRAM_CHAT_ID` di un container 5.0 vengono importati una volta al primo avvio della 5.1 e poi ignorati. I comandi in ingresso restano attivi (`notifications.telegram.commands`). |
|
||||
| D-32 | Le posizioni esterne vanno chiuse dal kill-switch di default? | no | **Default applicato**: `risk.closeForeignOnKill = false`; la conferma del kill-switch ha la spunta «chiudi anche le esterne», deselezionata. Dalla 5.1 la spunta parte uguale all'impostazione e la scelta fatta nel dialogo vale per quel kill-switch (D-55). |
|
||||
| D-33 | Valute del selettore oltre USD/EUR? | USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD | **Default applicato** (Fase 7). Per GBP e JPY il polling aggiunge GBPUSD e USDJPY. Dalla 5.1 il selettore sta solo in Impostazioni ▸ Interfaccia (richiesta dell'utente), non nella barra in alto. |
|
||||
| D-34 | Soglie di margine (40 % totale, 12 % per basket, buffer 25 %) e soglia di inattività (10 min)? | sì | **Default applicato** (Fasi 2 e 4), tutte in `strategy.json` e cambiabili dall'operatore. |
|
||||
| D-35 | Le orfane sul demo: bonifica con conferma o chiusura manuale? | bonifica con conferma | **Superata dai fatti**: il 2026-09-23 il conto demo ha 0 posizioni e 0 ordini; le 21 gambe del bot sono state chiuse in blocco il 21/9 alle 13:26 UTC (chiusura manuale, non del bot). La bonifica resta come comando (`--bonifica`, e pulsante in Diagnostica) per il futuro e non ha niente da chiudere oggi. |
|
||||
| D-36 | Il ledger delle sessioni 16-21/9 (65 `segnale_ingresso`/`rifiuto`) non è su questa macchina: `Documenti\Encelado\data\ledger\decisions.jsonl` ha solo il 16/9. Su quale macchina o profilo ha girato il bot? Puoi copiare qui `decisions.jsonl`, `baskets_state.json` e `learning_state.json` di quella sessione? | procedere con le evidenze dell'API | **Risposta dell'utente (2026-09-23)**: allegato il bundle della cartella dati dell'installazione 4.0.0. Letto: 1 813 righe dal 16/9 15:55 al 22/9 08:01, 65 `segnale_ingresso` e 65 `rifiuto` con motivazione «esito non ancora noto», preset AGGRESSIVE impostato dalla finestra, quattro run; `baskets_state.json` con `killSwitched = true` («kill-switch dalla finestra») e picco 149 552. L'equity registrata sale da 109 228 a 149 517 USD in circa ventuno scatti di ≈ +2 000 USD, uno per ogni esecuzione ridotta dal server: gli «accrediti» erano crediti virtuali del demo per ordine, non depositi. Post-mortem aggiornato. |
|
||||
| D-37 | Confermi che la chiusura in blocco del 21/9 alle 13:26 UTC l'hai fatta tu dalla piattaforma? | sì | **Risposta dell'utente (2026-09-23)**: «Sì, l'ho fatta io». Chiuso. |
|
||||
|
||||
## 5.1 — 2026-09-30
|
||||
|
||||
Domande nate dalle modifiche chieste in `Modifiche.txt` del 2026-09-30 (D-38…D-52) e dalla revisione della 5.1 del 2026-09-30/10-01 (D-53…D-58). L'utente ha scritto «fai domande se hai dei dubbi»: nessuna scelta era bloccante, quindi è stato applicato il default più prudente, e ognuna resta **in attesa di conferma del proprietario** finché non arriva una risposta.
|
||||
|
||||
| # | Domanda | Default proposto | Stato / risposta |
|
||||
|---|---|---|---|
|
||||
| D-38 | «P&L oggi» deve essere il realizzato delle posizioni chiuse oggi o la variazione dell'equity dalla mezzanotte (realizzato più aperto)? | realizzato | **Default applicato** (2026-09-30): il valore grande è il realizzato netto (`netProfit − fees`) delle posizioni del bot chiuse nella giornata UTC, dallo storico eToro (uguale al periodo «oggi» della pagina Storico; le posizioni esterne non contano); accanto c'è la variazione dell'equity netta da mezzanotte. La giornata è quella UTC, come il ledger. In attesa di conferma del proprietario. |
|
||||
| D-39 | Il nome della variabile della password: `ENCELADO_PASSWORD` va bene? | sì | **Default applicato** (2026-09-30), con `ENCELADO_WEB_TOKEN` accettato come alias perché il container 5.0.0 resti raggiungibile dopo l'aggiornamento (con valori diversi vince `ENCELADO_PASSWORD`). In attesa di conferma del proprietario. |
|
||||
| D-40 | I segreti (chiavi eToro, token Telegram) sono cifrati con una chiave ricavata dalla password: cambiare la password obbliga a sbloccarli con quella vecchia o a reinserirli. Va bene? | sì | **Default applicato** (2026-09-30, ADR-0010). Alternativa scartata: una chiave salvata su `/config`, che equivale al chiaro per chi legge la share. In attesa di conferma del proprietario. |
|
||||
| D-41 | Nel template restano la porta e le due cartelle `/config` e `/data`? | sì | **Default applicato** (2026-09-30): non sono impostazioni ma collegamenti del container; senza, configurazione e ledger si perderebbero a ogni aggiornamento. PUID/PGID (99/100) e TZ (lo aggiunge Unraid) tolti. In attesa di conferma del proprietario. |
|
||||
| D-42 | Passare da Demo a Live (o viceversa) con basket o ordini aperti? | rifiutato | **Default applicato** (2026-09-30): rifiutato finché il conto in uso non è piatto (si chiude, anche con il kill-switch, o si aspetta lo storico). Dalla revisione il controllo lo fa il motore sul suo thread e lo stato è per conto (D-53). In attesa di conferma del proprietario. |
|
||||
| D-43 | Un cambio di preset o di strategia con basket aperti? | vale per i nuovi | **Default applicato** (2026-09-30): i basket aperti conservano z di stop, aggiunte massime, TP, perdita massima e preset con cui sono entrati. In attesa di conferma del proprietario. |
|
||||
| D-44 | Avvio automatico del motore all'avvio del container? | sì, disattivabile | **Default applicato** (2026-09-30): impostazione `run.autostart` (attiva). In modalità Live il motore non parte mai da solo. In attesa di conferma del proprietario. |
|
||||
| D-45 | Il Live si conferma anche da riga di comando (`--confirm-live`)? | no | **Default applicato** (2026-09-30): la frase si scrive solo nell'interfaccia; `--confirm-live` ed `ENCELADO_CONFIRM_LIVE` non esistono più. In attesa di conferma del proprietario. |
|
||||
| D-46 | Le righe storiche del ledger con `mode = Paper`? | restano | **Default applicato** (2026-09-30): il ledger non si modifica; non contano per i 300 basket in Demo di ADR-0006. In attesa di conferma del proprietario. |
|
||||
| D-47 | Quali parametri di `strategy.json` mostrare in Impostazioni? | tutti, a gruppi | **Default applicato** (2026-09-30): preset, basket attivi, rischio e sicurezza, cancelli, apprendimento, recupero; indicatori e sovrascritture del preset nel gruppo «Avanzate», chiuso. In attesa di conferma del proprietario. |
|
||||
| D-48 | Le variabili della 5.0.0 già presenti nel container? | importate una volta, poi ignorate | **Default applicato** (2026-09-30): al primo avvio chiavi, token e chat vanno nel deposito cifrato e nel file (le chiavi nell'ordine della 5.0: ambiente, poi file, poi `etoro.keys.enc`); le impostazioni solo se diverse dal valore di fabbrica. Poi vengono ignorate e segnalate in Sistema: si possono togliere dal container. In attesa di conferma del proprietario. |
|
||||
| D-49 | Orologi: quali fusi? | uno per paese delle valute | **Default applicato** (2026-09-30): Nuova Zelanda, Australia, Europa centrale/Svizzera, USA/Canada orientale, con le bandiere; il fuso del PC compare solo se diverso da tutti (Europe/Rome coincide con l'Europa centrale). L'ora UTC resta nei tooltip. In attesa di conferma del proprietario. |
|
||||
| D-50 | Versione del rilascio? | 5.1.0 | **Default applicato** (2026-09-30): la minor successiva (regola della catena); la configurazione vecchia viene letta e migrata. `Directory.Build.props` porta 5.1.0. In attesa di conferma del proprietario. |
|
||||
| D-51 | Dati sbagliati scritti dalla 4.0.0/5.0.0 (P&L delle chiusure): correggerli? | sì, con righe di correzione | **Default applicato** (2026-09-30, ADR-0011): righe `correzione` in `decisions.jsonl`, modelli ritirati e riaddestrati sulle etichette corrette, bandit dal prior. I messaggi Telegram già inviati non si possono correggere. In attesa di conferma del proprietario. |
|
||||
| D-52 | Raggiunta la perdita giornaliera, le entrate restano bloccate fino a mezzanotte UTC anche se l'equity risale? | sì | **Default applicato** (2026-09-30, il più prudente, ed è la regola scritta in `RISK_RULES.md`): il blocco di nuove entrate e aggiunte resta fino alle 00:00 UTC, nel motore e nel backtest; il giorno del blocco è nello stato del conto e sopravvive a un riavvio. Sostituisce il comportamento della prima 5.1, che rivalutava la regola a ogni decisione. In attesa di conferma del proprietario. |
|
||||
| D-53 | Lo stato del motore (basket, chiusure in attesa del P&L, picco, flussi di cassa, blocchi, residui, pausa, giornata della perdita giornaliera) è uno solo o uno per conto? | uno per conto | **Default applicato** (2026-09-30, decisione della revisione): `data/state/baskets_state.demo.json` e `baskets_state.live.json` al posto di `baskets_state.json`. Un cambio di conto non sovrascrive né scarta niente dell'altro conto: tornando lo si ritrova com'era. Il file unico della versione precedente va una volta sola al suo conto e resta come `.migrato`: per la prima 5.1 il conto del suo `mode`; per la 5.0, dove `mode` era la modalità, il conto su cui operava la configurazione della 5.0, registrato dall'importazione (seconda revisione, 2026-10-01: un `Live` accanto a `demo` finiva al conto reale); Paper o una modalità diversa non vengono ripresi. `pending_orders.json` resta un file solo e ogni ordine porta il suo conto (`mode`): un motore non risolve, non fa fallire e non pota quelli dell'altro conto. La guardia del cambio è un comando sul thread di decisione (blocca le entrate, riconcilia con il conto, poi conta basket occupati, ordini, orfane e residui, chiusure in attesa), rifiutata mentre il motore si avvia o si ferma e ricontrollata sul disco dopo l'arresto: se fallisce i file delle impostazioni tornano come prima e niente parte. A motore fermo decide il file del conto in uso. In attesa di conferma del proprietario. |
|
||||
| D-54 | Un calo del saldo che lo storico eToro non spiega ancora (forse un prelievo) conta come perdita giornaliera? | blocca senza chiudere la giornata | **Default applicato** (2026-10-01): sospende subito nuove entrate e aggiunte (`dailyLossHit` senza `dailyLossLatched`, con un testo proprio in dashboard, Telegram e console), ma la giornata si blocca fino alle 00:00 UTC solo sulla perdita che resta anche se tutto quel calo fosse un prelievo; la lettura che lo spiega blocca il resto. La sospensione resta finché lo storico non spiega il calo, anche se intanto l'equity recupera, e quella lettura giudica la giornata sull'equity più bassa vista nel frattempo: una perdita la blocca anche se l'equity è risalita, un movimento di cassa (prelievo o deposito) mai (seconda revisione, 2026-10-01). Così un prelievo non blocca la giornata e una perdita non sfugge. In attesa di conferma del proprietario. |
|
||||
| D-55 | Kill-switch con posizioni esterne: vale la casella del dialogo o l'impostazione `risk.closeForeignOnKill`? | la scelta esplicita | **Default applicato** (2026-10-01): la casella del dialogo parte uguale all'impostazione e la scelta fatta lì vince (l'interfaccia manda sempre `foreign` esplicito); senza scelta (Telegram `/kill`, file `STOP`) vale l'impostazione; la console chiede solo se ci sono posizioni esterne e propone l'impostazione come risposta di partenza. La nota `kill_switch_avviato` dice chi ha deciso (`esterne_da`). In attesa di conferma del proprietario. |
|
||||
| D-56 | Dopo una password errata: un'attesa per tutto il server o per indirizzo? Il cookie conta come tentativo? | per indirizzo; no | **Default applicato** (2026-10-01): ogni password errata (form, `Authorization: Bearer`) costa al suo indirizzo (IPv6: il /64) un'attesa di 1, 2, 4, 8, 16, poi 30 s; il cookie non è un tentativo (seconda revisione: contato come tale, una scheda rimasta aperta dopo un cambio di password teneva l'indirizzo in attesa e la password giusta riceveva 429): contiene un segreto del server (`/config/session.key`), quindi non si calcola da una password indovinata; valido entra anche durante l'attesa, sbagliato riceve 401 subito; durante l'attesa nessuna password di quell'indirizzo viene controllata, nemmeno quella giusta (429), così i tentativi in parallelo non danno informazioni. Non globale: un altro computer della rete non deve poter tenere fuori l'operatore dal kill-switch. Una password giusta azzera il conto, dieci minuti senza errori lo dimenticano. Dietro un reverse proxy l'attesa vale per tutti i client che il proxy fa sembrare uno. In attesa di conferma del proprietario. |
|
||||
| D-57 | Fuori dal container (F5, `run-dev`) con la password impostata, il server si apre alla rete? | no | **Default applicato** (2026-10-01): la password di F5 e degli script (`sviluppo`) serve ai segreti della sandbox, non ad aprire il PC alla rete; il server ascolta su tutte le interfacce solo nel container o con l'argomento `--listen-all`. In attesa di conferma del proprietario. |
|
||||
| D-58 | FERMA (o un salvataggio che riavvia il motore) mentre è in corso un kill-switch, una chiusura o la chiusura dei residui? | rifiutato | **Default applicato** (2026-10-01): 409 con il motivo, da ripetere quando è concluso; un kill-switch tagliato a metà lascerebbe posizioni senza nessuno che le guardi. AVVIA subito dopo FERMA aspetta che il motore precedente abbia lasciato la cartella dati. Solo l'arresto del processo (`docker stop`) interrompe un kill-switch in corso, dopo 30 s, e registra il residuo (Halted-Residuo). In attesa di conferma del proprietario. |
|
||||
@@ -1,16 +1,19 @@
|
||||
# Regole di sicurezza e approvazione
|
||||
|
||||
Tutte le regole di §10 della specifica, con il valore di fabbrica, dove sta e chi può cambiarlo. "Operatore" è chi modifica i file in `Documenti\Encelado` o usa la finestra; "codice" vuol dire che non esiste una chiave di configurazione.
|
||||
Aggiornato: 2026-10-01 (5.1). Tutte le regole di §10 della specifica, con il valore di fabbrica, dove sta e chi può cambiarlo. «Operatore» è chi usa Impostazioni nell'interfaccia (o, a mano, i file in `/config`); «codice» vuol dire che non esiste una chiave di configurazione. Dalla 5.1 ogni impostazione si cambia dall'interfaccia e il bot la applica subito quando può (ADR-0010).
|
||||
|
||||
| Regola | Default | Dove | Chi la cambia |
|
||||
|---|---|---|---|
|
||||
| Modalità di esecuzione | `Demo` | `encelado.json` → `run.executionMode` (`Paper`, `Demo`, `Live`) | operatore; `Live` richiede `run.allowLive = true` **e** la frase `CONFERMO LIVE` scritta all'avvio (o `--confirm-live "CONFERMO LIVE"` in headless) |
|
||||
| Approvazione dei singoli ordini | nessuna, in nessuna modalità (D-20, ADR-0005) | codice | nessuno. Il bot apre, aggiunge e chiude da solo; i gate umani sono l'avvio del reale, il kill-switch, il reset dopo un equity stop e il cambio di preset |
|
||||
| Equity stop | 9 % dal picco di equity | `strategy.json` → `equityStopPct` | operatore; scatta → chiude tutto, blocca, richiede reset con motivazione scritta (finestra o `reset <motivo>` in headless), che finisce nel ledger; il picco riparte dall'equity del reset |
|
||||
| Perdita giornaliera massima | 3 % dell'equity di inizio giornata (UTC) | `strategy.json` → `dailyLossPct` | operatore; blocca le nuove entrate fino al giorno dopo, non chiude |
|
||||
| Rischio per basket | 0,25 / 0,50 / 1,00 % (preset) | `strategy.json` → preset o `riskPerBasketPct` | operatore; il cambio di preset a caldo non tocca i basket aperti |
|
||||
| Perdita massima per basket | 1,5 % dell'equity all'ingresso | `strategy.json` → `maxLossPerBasketPct` | operatore; mai disattivabile |
|
||||
| Stop di basket su z | 3,0 / 3,5 / 4,0 (preset) | `strategy.json` → preset o `zStop` | operatore; mai disattivabile (solo il backtest lo spegne, nel test di falsificazione 3) |
|
||||
| Modalità di esecuzione = conto | `Demo` (conto demo di eToro: ordini veri, denaro virtuale) | `encelado.json` → `run.executionMode` (`Demo`, `Live`; Impostazioni ▸ Conto). La modalità sceglie anche il conto: `Demo` = conto demo, `Live` = conto reale. `Paper` non esiste più (un file che la nomina si legge come `Demo` con un avviso) | operatore; `Live` richiede `run.allowLive = true` **e** la frase `CONFERMO LIVE` scritta nell'interfaccia a **ogni** avvio (dialogo di AVVIA) e prima di ogni cambio che riavvia il motore in Live. Nessuna variabile d'ambiente e nessun argomento da riga di comando la sostituiscono. **Il Live non parte mai da solo**: né all'avvio del container né dopo un riavvio automatico (allarme «LIVE: premi AVVIA» e avviso Telegram «Live: motore fermo»; le posizioni aperte hanno nel frattempo solo gli stop nativi) |
|
||||
| Cambio di conto (Demo ↔ Live) | rifiutato finché il conto in uso non è piatto | codice (guardia C8, D-42, D-53) | nessuno. Conta come «non piatto»: basket aperti o in attesa di una gamba, ingressi, aggiunte o uscite in corso, basket in errore con una gamba sul conto, ordini senza esito, gambe orfane del bot o residui del kill-switch, chiusure in attesa dello storico eToro (al più 30 minuti). A motore acceso il controllo lo fa il motore sul suo thread di decisione: prima blocca nuove entrate e aggiunte, poi riconcilia con il conto (una gamba del bot che nessuno slot tiene conta come orfana; posizioni non lette: rifiutato), poi conta; se il conto è libero le entrate restano bloccate fino al riavvio sull'altro conto, altrimenti il blocco si toglie. Rifiutato anche mentre il motore si avvia (finché il ciclo di decisione non è partito), mentre si ferma o se non risponde entro 30 s. Dopo l'arresto il file del conto lasciato viene giudicato di nuovo: se non è piatto (o nel frattempo è partito un kill-switch) `encelado.json` e `strategy.json` tornano byte per byte come prima e niente riparte. A motore fermo decide il file di stato del conto in uso. Lo stesso controllo vale per un cambio delle coppie dei basket |
|
||||
| Stato per conto | uno per conto | `data/state/baskets_state.demo.json`, `baskets_state.live.json` (D-53) | nessuno. Basket aperti, ingressi in sospeso, chiusure in attesa del P&L, picco di equity, flussi di cassa, equity stop, kill-switch e residuo, pausa dell'operatore e giornata della perdita giornaliera sono **del conto**: un cambio non li sovrascrive né li scarta, e tornando sull'altro conto li si ritrova. Un conto i cui basket nessuno ha seguito oltre `recovery.thresholdMinutes` (il bot girava sull'altro) riceve il recupero dopo inattività |
|
||||
| Approvazione dei singoli ordini | nessuna, in nessuna modalità (D-20, ADR-0005) | codice | nessuno. Il bot apre, aggiunge e chiude da solo; i gate umani sono l'avvio del reale, il kill-switch e il reset dopo un kill-switch o un equity stop |
|
||||
| Preset | `Moderate` | `strategy.json` → `preset` (Impostazioni ▸ Strategia) | operatore. Fa parte della strategia e resta fisso: non esiste più un comando per cambiarlo a caldo (né dall'interfaccia, né dalla console, né da Telegram). Un cambio vale per i basket **nuovi**: quelli aperti conservano z di stop, aggiunte massime, TP, perdita massima e preset con cui sono entrati (D-43). Il bandit lo propone soltanto |
|
||||
| Equity stop | 9 % dal picco di equity | `strategy.json` → `equityStopPct` | operatore; scatta → chiude tutto, blocca, richiede il reset con motivazione scritta (Sblocca… nell'interfaccia, `reset <motivo>` da console, `/reset <motivo>` da Telegram), che finisce nel ledger; il picco riparte dall'equity del reset |
|
||||
| Perdita giornaliera massima | 3 % dell'equity netta di inizio giornata (UTC). Formula (la stessa nel motore e nel backtest, `DailyLoss.IsHit`): `E₀ − E ≥ E₀ × dailyLossPct / 100`, dove `E = equity − cassa cumulata` è l'**equity netta** attuale (realizzato e aperto insieme, depositi e prelievi esclusi) ed `E₀` l'equity netta alla prima lettura del conto dopo le 00:00 UTC. Un deposito non nasconde una perdita, un prelievo non la inventa. «P&L oggi» è un'altra cosa: il realizzato netto (`netProfit − fees`) delle posizioni del bot chiuse oggi, dallo storico eToro; accanto c'è la «variazione dell'equity netta da mezzanotte» `E − E₀`, che è ciò che la regola guarda. Fino alla 5.0.0 la regola sommava i proceeds delle chiusure e non scattava mai dopo la prima chiusura del giorno | `strategy.json` → `dailyLossPct` | operatore. **Raggiunta una volta, niente nuove entrate né aggiunte fino alle 00:00 UTC, anche se l'equity recupera** (D-52; `DailyLossLatch` nel motore, `ReplayDailyLoss` nel backtest, stessa regola); non chiude niente e non richiede reset. Si giudica a ogni lettura del conto e a ogni decisione. Il giorno del blocco è nello stato del conto (`dailyLossDay`): un riavvio nello stesso giorno lo mantiene, il nuovo giorno UTC lo toglie. Un calo del saldo che lo storico eToro non spiega ancora (forse un prelievo) sospende subito le entrate finché non si chiarisce, anche se intanto l'equity recupera, ma blocca la giornata solo quando risulta una perdita: la lettura che lo spiega la giudica sull'equity più bassa vista nel frattempo (D-54) |
|
||||
| Rischio per basket | 0,25 / 0,50 / 1,00 % (preset) | `strategy.json` → preset o `riskPerBasketPct` (Impostazioni ▸ Strategia ▸ avanzate) | operatore; vale per i basket nuovi |
|
||||
| Perdita massima per basket | 1,5 % dell'equity all'ingresso | `strategy.json` → `maxLossPerBasketPct` | operatore; mai disattivabile; fissata in USD all'ingresso (un basket aperto tiene il limite con cui è entrato) |
|
||||
| Stop di basket su z | 3,0 / 3,5 / 4,0 (preset) | `strategy.json` → preset o `zStop` | operatore; mai disattivabile (solo il backtest lo spegne, nel test di falsificazione 3); un basket aperto tiene lo z di stop con cui è entrato |
|
||||
| Basket aperti | 2 / 3 / 5 (preset) | `strategy.json` → preset o `maxBaskets` | operatore |
|
||||
| Un solo basket per cross sintetico | `Exclusive` | `strategy.json` → `sameCrossPolicy` | operatore (`Half` dimezza la size di entrambi) |
|
||||
| Leva effettiva massima | 10:1 sul nozionale complessivo | `strategy.json` → `maxEffectiveLeverage` | operatore, tetto 30 |
|
||||
@@ -31,19 +34,24 @@ Tutte le regole di §10 della specifica, con il valore di fabbrica, dove sta e c
|
||||
| Quotazione vecchia | > 15 s → niente nuove entrate | codice (`BasketEngine.MaxQuoteAgeSeconds`) | nessuno |
|
||||
| Qualità dati | buco > 2 h feriale o salto > 8 σ → decisioni sospese su quella barra | codice | nessuno |
|
||||
| Leg-risk | seconda gamba **rifiutata** → chiudi subito la prima (`leg_risk_unwind`), basket in pausa 1 h. Seconda gamba **senza esito** entro `legTimeoutSec` (5 s) → basket in `PendingB`: il registro degli ordini continua a chiedere; eseguita → basket aperto; rifiutata → prima gamba richiusa | `strategy.json` → `legTimeoutSec` (pausa: codice) | operatore (timeout) |
|
||||
| Ordine dall'esito ignoto | mai abbandonato: registrato in `data/state/pending_orders.json` **prima** dell'invio; esito chiesto per `orderId` (ogni 2 s nel primo minuto, poi ogni 10 s, poi ogni minuto) e riconosciuto anche dalla posizione comparsa sul conto (stesso strumento e verso, entro 90 s); una gamba A senza esito porta il basket in `PendingA` (nessun nuovo ordine su quel basket); all'avvio i pendenti si risolvono prima di qualsiasi decisione | codice (ADR-0009) | nessuno |
|
||||
| Ordine dall'esito ignoto | mai abbandonato: registrato in `data/state/pending_orders.json` **prima** dell'invio, con il suo conto (`mode`); esito chiesto per `orderId` (ogni 2 s nel primo minuto, poi ogni 10 s, poi ogni minuto) e riconosciuto anche dalla posizione comparsa sul conto (stesso strumento e verso, entro 90 s); una gamba A senza esito porta il basket in `PendingA` (nessun nuovo ordine su quel basket); all'avvio i pendenti del conto si risolvono prima di qualsiasi decisione; un motore non tocca gli ordini dell'altro conto | codice (ADR-0009) | nessuno |
|
||||
| Gamba A eseguita in ritardo | segnale ancora valido e nessun blocco → gamba B (ridimensionata sulle unità eseguite di A); altrimenti chiusura immediata di A (`leg_risk_unwind`) | codice | nessuno |
|
||||
| Gamba orfana del bot | una gamba di un basket sparisce dal conto → l'altra viene chiusa alla riconciliazione successiva. Una posizione che porta la firma del bot (id nel registro, oppure strumento + verso + orario entro 90 s da una riga `segnale_ingresso`/`rifiuto`/`ingresso`/`pending` del ledger) ma non appartiene a nessun basket è `orfana-bot`: **adottata e chiusa** (tre tentativi, poi entrate bloccate con avviso). Contatore «orfane» in dashboard, rosso se > 0 | codice; `--bonifica` all'avvio la elenca e chiede conferma per ognuna | operatore (bonifica) |
|
||||
| Movimenti di cassa | un salto del saldo non spiegato dalle chiusure (oltre 10 USD e 0,25 %) è un deposito o un prelievo: scritto nel ledger come `movimento_di_cassa`, escluso dal P&L, dal picco di equity e dal drawdown | codice (`EquityTracker`) | nessuno |
|
||||
| Posizioni non riconciliate | se il P&L aperto del conto e la somma delle posizioni non tornano (oltre 5 USD e 1 %) per più di 60 s, o un basket ha una gamba che il conto non mostra: avviso «posizioni non riconciliate» (banner giallo, riga di stato) | codice | nessuno |
|
||||
| Una posizione, una riga | ogni posizione chiusa finisce in `baskets.csv` una volta sola, da qualunque percorso la veda chiudersi (uscita del basket, residuo del kill-switch, riconciliazione, orfana richiusa); le gambe di un basket rimaste nel residuo di un kill-switch diventano una riga sola, come basket (`exit_reason = kill_switch`), quando sono tutte chiuse | codice | nessuno |
|
||||
| Movimenti di cassa | un salto del saldo non spiegato dalle chiusure (oltre 10 USD e 0,25 %) è un deposito o un prelievo: scritto nel ledger come `movimento_di_cassa`, escluso dal P&L, dal picco di equity e dal drawdown. Finché lo storico eToro non mostra una chiusura, il saldo non viene giudicato; dopo un'ora una posizione sparita che lo storico ancora non mostra non trattiene più il giudizio | codice (`EquityTracker`) | nessuno |
|
||||
| Saldo all'avvio | il saldo salvato si confronta con quello nuovo (chiusure contro movimenti di cassa) solo quando lo storico eToro mostra **ogni** posizione chiusa da allora (sparite dal conto, sparite senza verdetto, chiusure in attesa); altrimenti il saldo salvato resta il riferimento e giudica la riconciliazione che le vede (limite di un'ora): una chiusura non ancora nello storico non viene mai scritta come prelievo | codice (`StartupCash`) | nessuno |
|
||||
| Posizioni non riconciliate | se il P&L aperto del conto e la somma delle posizioni non tornano (oltre 5 USD e 1 %) per più di 60 s, o un basket ha una gamba che il conto non mostra: avviso «posizioni non riconciliate» (striscia degli allarmi, riga di stato) | codice | nessuno |
|
||||
| Chiusura incompleta | una gamba non chiude dopo 3 tentativi → stato `Error`, entrate bloccate, allarme | codice | nessuno; si risolve a mano sul conto e con la riconciliazione |
|
||||
| Kill-switch | pulsante con conferma, `kill` da console, file `STOP` in `Documenti\Encelado` (controllato ogni 5 s): blocco delle entrate, annullamento degli ordini senza esito (attesa ≤ 30 s), chiusura di **tutte le posizioni del bot** (basket, gambe in attesa, orfane; tre tentativi per gamba), esterne solo se chiesto o `risk.closeForeignOnKill`, **verifica di piattezza** sul conto (≤ 120 s); ciò che resta è `Halted-Residuo` con l'elenco, e nessuna dichiarazione di «tutto chiuso» senza la verifica | codice (ADR-0009, §9 del piano 5.0) | operatore |
|
||||
| Kill-switch | pulsante KILL con conferma, `kill` da console, `/kill CONFERMO` da Telegram, file `STOP` nella cartella della configurazione (`/config` nel container; controllato ogni 5 s): blocco delle entrate, annullamento degli ordini senza esito (attesa ≤ 30 s), chiusura di **tutte le posizioni del bot** (basket, gambe in attesa, orfane; tre tentativi per gamba), **verifica di piattezza** sul conto (≤ 120 s); ciò che resta è `Halted-Residuo` con l'elenco, e nessuna dichiarazione di «tutto chiuso» senza la verifica. Posizioni esterne: la scelta **esplicita** vince (la casella del dialogo, che parte uguale a `risk.closeForeignOnKill`; la risposta della console, che chiede solo se ce ne sono); senza scelta (Telegram `/kill`, file `STOP`) vale l'impostazione (D-55). Un kill-switch in corso **non viene mai interrotto** da FERMA o da un riavvio automatico (409, D-58); solo l'arresto del processo lo interrompe, dopo 30 s, e registra il residuo (riga `kill_switch_interrotto`, stato `Halted-Residuo`) | codice (ADR-0009, ADR-0012) | operatore |
|
||||
| Chiusura all'arresto | spenta: FERMA e lo spegnimento del container lasciano i basket sul conto con gli stop nativi (nessuno applica TP e stop di basket finché il bot non riparte) | `encelado.json` → `run.closeOnShutdown` (Impostazioni ▸ Esecuzione) | operatore. Accesa: il motore, sul suo thread di decisione, blocca prima nuove entrate e aggiunte, poi chiude basket, gambe in attesa e orfane, al più in 30 s; poi si ferma comunque. Un riavvio automatico dopo un cambio delle impostazioni non chiude mai niente |
|
||||
| Comandi critici | un kill-switch, una chiusura (`close`), la chiusura dei residui o una chiusura della bonifica in coda o in corso non vengono interrotti da FERMA, né da un salvataggio delle impostazioni o delle chiavi che riavvierebbe il motore: rispondono 409 prima di scrivere niente. Contano finché il motore li ha in mano, anche se chi li ha chiesti ha smesso di aspettare (scheda chiusa, 504 dopo 120 s, Telegram spento) | codice (ADR-0012) | nessuno |
|
||||
| Recupero dopo inattività | oltre `recovery.thresholdMinutes` (10) senza heartbeat o senza cicli: entrate bloccate, ordini pendenti risolti, riconciliazione, riscaldamento con le barre perse, ogni basket aperto rivalutato con le regole di uscita ordinarie (con le barre di inattività nel time-stop) → chiudi o tieni; orfane chiuse, esterne riportate; rapporto `reports/recupero_<run_id>.csv`; entrate riaperte dopo `recovery.warmupMinutes` (15); a mercato chiuso niente di irreversibile | `strategy.json` → `recovery` | operatore |
|
||||
| Una sola istanza | `data/state/instance.lock` tenuto in esclusiva: un secondo bot sulla stessa cartella dati non parte | codice | nessuno |
|
||||
| Una sola istanza | `data/state/instance.lock` tenuto in esclusiva: un secondo bot sulla stessa cartella dati non parte; lo prendono anche il ciclo di apprendimento a motore fermo e `backtest learn` | codice | nessuno |
|
||||
| Ripristino | procedura in cinque passi: stato, rimozione del file `STOP`, motivazione ≥ 10 caratteri (`correzione`), riconciliazione + riscaldamento + picco di equity al netto dei movimenti di cassa, ripartenza con entrate bloccate per `recovery.warmupMinutes`; rifiutato (`reset_rifiutato`) finché una posizione del bot resta sul conto | codice | operatore |
|
||||
| Posizioni esterne | posizioni senza la firma del bot: segnalate una volta nel log, contate in dashboard, **mai toccate** (dalla Fase 3: chiuse dal kill-switch solo con `risk.closeForeignOnKill` o con la spunta esplicita) | codice | operatore |
|
||||
| Chiavi API | solo `%LOCALAPPDATA%\Encelado\etoro.dat` (DPAPI) o `ETORO_API_KEY`/`ETORO_USER_KEY`; mai nel repo (`.gitignore`: `*.local.json`, `.env`) | codice | operatore |
|
||||
| Ambiente visibile | badge `PAPER/DEMO/LIVE` nella barra, nel log e nel ledger (`mode`) | codice | nessuno |
|
||||
| Controlli all'avvio | chiavi (profilo), orologio, strumenti e limiti, conto, riconciliazione, calendario | codice | nessuno; se falliscono il bot resta in sola lettura o non parte |
|
||||
| Averaging | `Off` in live; `AddOnce` ammesso in paper; moltiplicatore di lotto 1,0 | `strategy.json` → `averagingMode`, `lotMultiplier` (max 1,5, solo backtest) | operatore |
|
||||
| Parametri cambiati dal bot | mai. Le proposte vanno in `knowledge/proposals.csv` e passano dal forward test. Dalla 5.0 anche il bandit **propone soltanto**: fino alla 4.0.0 applicava il preset da solo in Paper e Demo (D-30) | codice | operatore |
|
||||
| Posizioni esterne | posizioni senza la firma del bot: segnalate una volta nel log, contate in dashboard, **mai toccate**, salvo dal kill-switch con la scelta esplicita o con `risk.closeForeignOnKill` (vedi sopra) | codice | operatore |
|
||||
| Chiavi API e token Telegram | solo in `/config/secrets.enc` (AES-256-GCM, chiave PBKDF2-SHA256 600 000 iterazioni dalla password dell'interfaccia), inserite e verificate da Impostazioni (Conto, Notifiche Telegram); mai nel repo, nel log, in `encelado.json` o nell'ambiente. Un'intestazione con meno di 100 000 o più di 10 000 000 iterazioni è un file danneggiato, bloccato senza derivare la chiave. Password cambiata → deposito bloccato: sblocco con la precedente o ripartenza con un `.bak`. L'importazione una tantum dalla 5.0 prende le chiavi nell'ordine ambiente, chiavi scritte nel file, vecchio `etoro.keys.enc` | codice (ADR-0010) | operatore |
|
||||
| Accesso all'interfaccia | password `ENCELADO_PASSWORD` (alias deprecato `ENCELADO_WEB_TOKEN`); cookie `encelado_session`, un HMAC della password e di un segreto del server (`/config/session.key`), Bearer per gli script. Ogni password errata (form o Bearer) costa al suo indirizzo un'attesa di 1, 2, 4, 8, 16, poi 30 s; durante l'attesa le richieste di quell'indirizzo con una password ricevono 429 (D-56); un cookie valido entra comunque, uno sbagliato riceve 401 subito. Le richieste che cambiano qualcosa sotto `/api/` devono dire `Content-Type: application/json` (415) e venire dalla stessa origine (`Origin`, `Sec-Fetch-Site`: 403); senza password il server risponde solo a un `Host` locale (403 altrimenti). Rete: su tutte le interfacce solo con la password, nel container o con `--listen-all` (D-57); altrimenti solo localhost | codice (ADR-0010) | operatore (la password, nel template del container) |
|
||||
| Ambiente visibile | pill del motore `DEMO`/`LIVE` nella barra in alto (LIVE su fondo rosso), nel log e nel ledger (`mode`) | codice | nessuno |
|
||||
| Controlli all'avvio | segreti leggibili e chiavi del conto della modalità, profilo, orologio, strumenti e limiti, conto, verifica del realizzato sullo storico, riconciliazione, calendario | codice | nessuno; se falliscono il bot resta in sola lettura o non parte, e l'interfaccia dice perché |
|
||||
| Averaging | `Off` di fabbrica; `AddOnce` e `Grid` ammessi; moltiplicatore di lotto 1,0 (niente martingala) | `strategy.json` → `averagingMode`, `lotMultiplier` (in sola lettura in Impostazioni; fino a 1,5 solo nel backtest) | operatore |
|
||||
| Parametri cambiati dal bot | mai. Le proposte vanno in `knowledge/proposals.csv` e passano dal forward test. Dalla 5.0 anche il bandit **propone soltanto**: fino alla 4.0.0 applicava il preset da solo (D-30) | codice | operatore |
|
||||
@@ -1,153 +1,217 @@
|
||||
# Runbook
|
||||
|
||||
Aggiornato: 2026-09-23 (5.0). Come si avvia, si ferma, si sblocca e si ripara il bot. Dalla 5.0 il bot gira nel container (`docs/DOCKER.md`, `deploy/unraid/`): i file dell'operatore stanno in `/config` (configurazione, chiavi cifrate, file `STOP`) e `/data` (ledger, stato, log). Fuori dal container, solo per lo sviluppo, valgono `Documenti\Encelado` e le stesse regole.
|
||||
Aggiornato: 2026-10-01 (5.1). Come si avvia, si ferma, si sblocca e si ripara il bot. Il bot gira nel container (`docs/DOCKER.md`, `deploy/unraid/`): i file dell'operatore stanno in `/config` (configurazione, segreti cifrati, file `STOP`) e `/data` (ledger, stato, log). Dalla 5.1 **tutto si imposta dall'interfaccia** (ADR-0010): nel container c'è solo la password. Fuori dal container, solo per lo sviluppo, valgono la sandbox `deploy/local/` (o `Documenti\Encelado`) e le stesse regole.
|
||||
|
||||
## Prima volta
|
||||
|
||||
1. Avvia il container (template Unraid o `docker run`, vedi `docs/DOCKER.md`) con `ENCELADO_WEB_TOKEN` impostato. Al primo avvio vengono creati `encelado.json` e `strategy.json` in `/config` dalle copie di fabbrica.
|
||||
2. Apri `http://<ip>:8080/`, inserisci il token (resta in un cookie per trenta giorni).
|
||||
3. Chiavi eToro Public API (`x-api-key` e `x-user-key`, dal portale sviluppatori; demo e reale hanno chiavi diverse): o nelle variabili `ETORO_API_KEY`/`ETORO_USER_KEY` del container (hanno la precedenza), oppure da **Impostazioni ▸ Chiavi eToro** con `ENCELADO_KEY_PASSPHRASE` impostata: il server le verifica con due letture (profilo e conto) e le salva cifrate in `/config/etoro.keys.enc`.
|
||||
4. Controlla in **Impostazioni**: ambiente `demo`, modalità `Demo`, fuso orario (o `TZ` del container), valuta di visualizzazione.
|
||||
5. Con `ENCELADO_AUTOSTART=1` (default) il motore è già partito; altrimenti premi **AVVIA**.
|
||||
1. Avvia il container (template Unraid o `docker run`, vedi `docs/DOCKER.md`) con la sola variabile `ENCELADO_PASSWORD` («Password interfaccia»: una frase lunga a piacere). Al primo avvio vengono creati `encelado.json` e `strategy.json` in `/config` dalle copie di fabbrica.
|
||||
2. Apri `http://<ip>:8080/` e scrivi la password (resta in un cookie per trenta giorni).
|
||||
3. **Impostazioni ▸ Conto**: il conto è `Demo` di fabbrica. Nella scheda delle chiavi del conto demo incolla `x-api-key` e `x-user-key` (dal portale sviluppatori eToro; demo e reale hanno chiavi diverse) e premi **Verifica e salva**: il server le prova con due letture (profilo e saldo) su quel conto e le salva cifrate in `/config/secrets.enc` con la password dell'interfaccia. Le chiavi del conto reale si inseriscono nella loro scheda, quando servono.
|
||||
4. Controlla il resto quando vuoi: valuta e tema in Impostazioni ▸ Interfaccia, preset e rischio in Strategia, Telegram in Notifiche Telegram (vedi sotto). Ogni cambio si applica subito.
|
||||
5. Premi **AVVIA** (⏻ in alto a destra). Con «Avvio automatico» acceso (Impostazioni ▸ Esecuzione, di fabbrica) dal riavvio successivo del container il motore parte da solo; al primo avvio, senza chiavi, non può partire e la striscia degli allarmi dice «SENZA CHIAVI: Nessuna chiave eToro salvata».
|
||||
|
||||
Per Telegram: `TELEGRAM_BOT_TOKEN` e `TELEGRAM_CHAT_ID` (vedi la sezione Telegram).
|
||||
## Aggiornare un container 5.0 alla 5.1
|
||||
|
||||
Passo per passo in `deploy/unraid/README.md`. In breve:
|
||||
|
||||
1. Al **primo avvio della 5.1** tieni le variabili della 5.0 come sono: chiavi eToro (`ETORO_API_KEY`/`ETORO_USER_KEY`, o il vecchio `/config/etoro.keys.enc` con `ENCELADO_KEY_PASSPHRASE`), token e chat Telegram e le impostazioni diverse dal valore di fabbrica vengono importati **una volta** nel deposito cifrato e in `encelado.json` (il log dice «importazione una tantum dalla 5.0: …»; `/config/import-5.1.json` lo ricorda). Il vecchio `etoro.keys.enc` diventa `etoro.keys.enc.migrato`.
|
||||
2. **Rinomina `ENCELADO_WEB_TOKEN` in `ENCELADO_PASSWORD` con lo stesso valore**: la password resta quella, e i segreti cifrati con lei restano leggibili. `ENCELADO_WEB_TOKEN` funziona ancora come alias, con un avviso.
|
||||
3. Dopo il primo avvio togli le altre variabili dal container: da lì in poi sono **ignorate** e la striscia degli allarmi e Sistema ▸ Segreti le elencano («puoi toglierla dal container»).
|
||||
4. Il primo avvio sposta lo stato del motore nel file del suo conto (`data/state/baskets_state.json` → `baskets_state.demo.json` o `.live.json`, l'originale resta come `.migrato`): il conto è quello su cui operava la configurazione della 5.0 (un `Live` con `etoro.environment` demo era il conto demo); lo stato della modalità Paper, o scritto con un'altra modalità, non viene ripreso e il log lo dice («non ripreso: …»): le posizioni si riconciliano dal conto, verifica sullo storico eToro il realizzato delle righe della 4.0.0-5.0.0 (righe `correzione`, «verifica del realizzato» nel log) e, se ne ha corrette, ritira una volta i modelli addestrati sui proceeds (`data/models/ritirati/…`). Poi: **Esegui ciclo** nella pagina Apprendimento, per rigenerare calibrazione e intuizioni sulle etichette corrette, e in `knowledge/proposals.csv` segna `respinta` le proposte nate dalle etichette sbagliate (la pagina le segnala con «basato su dati sospetti»).
|
||||
5. Se la password cambia (anche per sbaglio), i segreti risultano **bloccati**: vedi «Segreti».
|
||||
|
||||
## Sviluppo sul PC
|
||||
|
||||
Per vedere e provare il bot senza Unraid: **F5** in VS Code (`Encelado (server)`), `scripts\run-dev.ps1` o `scripts\run-docker.ps1` (il container dalla compose). Tutti usano la sandbox `deploy/local/` come `/config` e `/data`; dettagli in `docs/DOCKER.md`. Con `--sample` (o `Encelado (campione)`) la pagina mostra dati finti senza chiavi.
|
||||
Per vedere e provare il bot senza Unraid: **F5** in VS Code (`Encelado (server)`), `scripts\run-dev.ps1` o `scripts\run-docker.ps1` (il container dalla compose). Tutti usano la sandbox `deploy/local/` come `/config` e `/data` e la password `sviluppo`, così i segreti salvati da Impostazioni valgono in tutti e tre i modi (dettagli in `docs/DOCKER.md`). F5 e `run-dev` restano **su localhost** anche con la password (la password serve ai segreti della sandbox); per raggiungerli da un altro PC serve l'argomento `--listen-all`. Con `--sample` (o `Encelado (campione)`, `run-dev -Sample`) il server mostra dati d'esempio in cartelle temporanee: non tocca la sandbox, i segreti, Telegram né `Documenti\Encelado`, e ogni comando o salvataggio risponde «modalità dimostrativa».
|
||||
|
||||
## Modalità
|
||||
## Modalità e conto
|
||||
|
||||
| Modalità | Ordini | Conferma all'avvio |
|
||||
| Modalità | Conto e ordini | Avvio |
|
||||
|---|---|---|
|
||||
| `Paper` | simulatore locale sopra le quotazioni reali (`data/state/paper_state.json`) | nessuna |
|
||||
| `Demo` (default) | conto demo eToro, denaro virtuale | nessuna |
|
||||
| `Live` | conto reale | `run.allowLive = true` **e** la frase `CONFERMO LIVE` (dialogo di AVVIA, oppure `ENCELADO_CONFIRM_LIVE` per l'avvio automatico, oppure `--confirm-live`) |
|
||||
| `Demo` (default) | conto demo eToro: ordini veri, denaro virtuale | AVVIA, o da solo con «Avvio automatico» |
|
||||
| `Live` | conto reale | `run.allowLive` («Consenti il conto reale», Impostazioni ▸ Conto) **e** la frase `CONFERMO LIVE` scritta nel dialogo di AVVIA, a **ogni** avvio. Il Live **non parte mai da solo**: dopo un riavvio del container il motore resta fermo, la striscia degli allarmi dice «LIVE: premi AVVIA» e Telegram manda «Live: motore fermo»; nel frattempo i basket aperti hanno solo gli stop nativi |
|
||||
|
||||
In ogni modalità il bot apre e chiude da solo (decisione D-20). Il chip in basso a sinistra del rail dice sempre in che ambiente sei (`PAPER` blu, `DEMO` giallo, `LIVE` rosso).
|
||||
`Paper` non esiste più (un file della 5.0 che la nomina si legge come `Demo`, con un avviso). La modalità è anche il conto: `Demo` lavora sul conto demo con le sue chiavi, `Live` sul reale con le sue. In ogni modalità il bot apre e chiude da solo (D-20). La pill del motore nella barra in alto dice sempre su che conto sei: `DEMO` con il bordo accento, `LIVE` su fondo rosso; il pallino dice lo stato (verde in esecuzione, grigio fermo, ambra in avvio o arresto, pausa, entrate bloccate, recupero, perdita giornaliera, heartbeat in ritardo; rosso in errore o bloccato).
|
||||
|
||||
### Cambiare conto (Demo ↔ Live)
|
||||
|
||||
Da Impostazioni ▸ Conto. Il cambio è **rifiutato** (409, niente salvato) finché sul conto in uso c'è qualcosa in sospeso, e il messaggio dice cosa e cosa fare:
|
||||
|
||||
| Cosa blocca | Cosa fare |
|
||||
|---|---|
|
||||
| basket aperti o in attesa di una gamba, ingressi, aggiunte o uscite in corso, basket in errore con una gamba sul conto | chiudili (chiudi basket, o il kill-switch), oppure aspetta che l'ingresso finisca |
|
||||
| ordini senza esito | aspetta che il registro li risolva (Storico ▸ Ordini) |
|
||||
| gambe orfane del bot o residui del kill-switch | «Chiudi residui» / bonifica, poi riprova |
|
||||
| chiusure in attesa dello storico eToro | con il motore acceso aspetta (al più 30 minuti); con il motore fermo avvialo su quel conto perché le regoli |
|
||||
| il motore si sta avviando (finché il ciclo di decisione non è partito: verifica, riscaldamento, riconciliazione), si sta fermando, o non risponde entro 30 s | riprova fra poco |
|
||||
|
||||
Con il motore acceso è il motore stesso a controllare, dopo aver bloccato le nuove entrate (nella striscia «cambio di conto verso … in corso» per qualche secondo) e riletto le posizioni del conto (una gamba del bot rimasta sola conta come orfana; se eToro non risponde il cambio è rifiutato: riprova); poi si ferma senza chiudere niente e riparte sull'altro conto (in Live con la frase). Se dopo l'arresto il conto lasciato risulta non piatto (un ingresso finito all'ultimo, un kill-switch partito nel frattempo, FERMA), il salvataggio viene **annullato** — `encelado.json` e `strategy.json` tornano come prima — e il messaggio lo dice: il motore resta fermo (premi AVVIA) o acceso sul conto di prima. **Ogni conto ha il suo stato** (`baskets_state.demo.json`, `baskets_state.live.json`): basket, blocchi, residui, pausa, picco, chiusure in attesa e giornata della perdita giornaliera dell'altro conto non vengono toccati, e tornando lo si ritrova com'era. Se i basket di un conto sono rimasti senza nessuno che li seguisse oltre `recovery.thresholdMinutes`, al ritorno parte il recupero dopo inattività.
|
||||
|
||||
## Impostazioni
|
||||
|
||||
Ogni campo ha un'icona che dice quando vale: ⚡ subito (log, interfaccia, Telegram), ⚙ nel motore in esecuzione, senza riavvio (strategia, intervalli, timeout; riga `configurazione` nel ledger), ↻ con un riavvio automatico del motore, che **non chiude** i basket (conto, chiavi del conto in uso, coppie dei basket, «Legge anche i cross diretti»). «Salva (n)» manda solo i campi cambiati e l'esito di ognuno compare accanto. In Live un cambio che riavvia il motore chiede prima la frase `CONFERMO LIVE`. Un salvataggio che riavvierebbe il motore mentre è in corso un kill-switch, una chiusura o la chiusura dei residui è rifiutato (409): ripeti quando è concluso. Se nel frattempo hai premuto FERMA, i valori vengono salvati e valgono al prossimo avvio. Il preset si sceglie in Strategia e vale per i basket nuovi: quelli aperti tengono z di stop, aggiunte, TP, perdita massima e preset con cui sono entrati. **Valori predefiniti ▸ Ripristina** (a motore fermo) rimette `encelado.json` di fabbrica, con un backup datato accanto.
|
||||
|
||||
## Segreti
|
||||
|
||||
Le chiavi eToro dei due conti e il token Telegram stanno solo in `/config/secrets.enc`, cifrati con la password dell'interfaccia; mai nel log, nel file di configurazione o nell'ambiente.
|
||||
|
||||
- **Chiavi**: Impostazioni ▸ Conto, una scheda per conto, «Verifica e salva» (le prova su quel conto) e «Rimuovi» (a motore fermo, o del conto non in uso). Nuove chiavi del conto in uso con il motore acceso lo riavviano (Live: con la frase). La verifica dura fino a 25 s: se intanto il conto è cambiato, le chiavi vengono salvate e riavviano il motore solo se sono del conto su cui lavora ora (in Live solo con la frase; senza, il messaggio dice di premere FERMA e poi AVVIA).
|
||||
- **Token Telegram**: Impostazioni ▸ Notifiche Telegram, verificato con `getMe`; «Invia messaggio di prova».
|
||||
- **Segreti bloccati** (la password del container è cambiata, o il file è danneggiato): striscia rossa «SEGRETI BLOCCATI», il motore non parte. In Impostazioni ▸ Conto: **Sblocca con la password precedente** (decifra con la vecchia e ricifra con quella attuale), oppure **Ricomincia** (deposito vuoto; il vecchio file resta come `secrets.enc.<data>.bak`) e reinserisci chiavi e token.
|
||||
- Senza password (solo sviluppo su localhost) la chiave è un file casuale `secrets.key`; quando una password compare, i segreti vengono ricifrati con lei e il file sparisce.
|
||||
|
||||
## Accesso all'interfaccia
|
||||
|
||||
- La password si scrive una volta nella pagina di accesso; «Esci» (Impostazioni ▸ Interfaccia o Sistema) toglie il cookie. Cambiare la password del container chiude tutte le sessioni (e blocca i segreti: vedi sopra); anche cancellare `/config/session.key` (il segreto del server nel cookie) le chiude. Dopo l'aggiornamento alla 5.1 serve un nuovo accesso.
|
||||
- Dopo una password errata (pagina di accesso o `Authorization: Bearer`) l'indirizzo che l'ha mandata aspetta 1 s, poi 2, 4, 8, 16, fino a 30 s per ogni errore di fila; nel frattempo un'altra password da lì riceve «Troppi tentativi… riprova fra N secondi» (429), anche quella giusta. Una pagina già entrata non aspetta, e una scheda rimasta aperta dopo un cambio di password torna da sola alla pagina di accesso senza far aspettare nessuno.
|
||||
- Dagli script: `Authorization: Bearer <password>` e, per ogni POST o DELETE sotto `/api/`, `Content-Type: application/json` anche senza corpo (altrimenti 415), per esempio `curl -X POST -H "Authorization: Bearer $PASSWORD" -H "Content-Type: application/json" http://<ip>:8080/api/commands/pause`.
|
||||
- Dietro un reverse proxy il proxy deve passare l'`Host` originale o `X-Forwarded-Host`, altrimenti ogni comando riceve 403 (`docs/DOCKER.md`, «Rete»).
|
||||
|
||||
## Console e comandi
|
||||
|
||||
Il processo stampa il log su stdout (`docker logs -f encelado`) e una riga di stato ogni `run.statusSeconds`. Con un terminale collegato (`docker attach`, o il processo lanciato a mano) accetta comandi da tastiera: `status`, `close <basket>`, `kill`, `residuo [id]`, `preset <nome>`, `bonifica`, `reset <motivazione>`, `stop`. Gli stessi comandi esistono nell'interfaccia (pulsanti e dialoghi) e in Telegram. Argomenti: `--no-autostart`, `--minutes N` (arresto automatico), `--bonifica`, `--confirm-live "CONFERMO LIVE"`, `--port N`, `--sample`, `--health`.
|
||||
Il processo stampa il log su stdout (`docker logs -f encelado`) e una riga di stato ogni `run.statusSeconds`. Con un terminale collegato (`docker attach`, o il processo lanciato a mano) accetta comandi da tastiera: `status`, `close <basket>`, `kill` (chiede delle posizioni esterne solo se ce ne sono, con l'impostazione come risposta di partenza), `residuo [id]`, `bonifica`, `reset <motivazione>`, `stop`. Gli stessi comandi esistono nell'interfaccia (pulsanti e dialoghi) e in Telegram. Il preset non è un comando: si sceglie in Impostazioni ▸ Strategia. Argomenti: `--no-autostart`, `--minutes N` (arresto automatico), `--bonifica`, `--port N`, `--listen-all` (fuori dal container, la rete con la password), `--sample`, `--health`.
|
||||
|
||||
**Una sola istanza per cartella dati**, imposta dal lock `data/state/instance.lock`: un secondo processo sulla stessa cartella viene rifiutato con il pid del primo.
|
||||
**Una sola istanza per cartella dati**, imposta dal lock `data/state/instance.lock`: un secondo processo sulla stessa cartella viene rifiutato con il pid del primo; lo stesso lock lo prendono il ciclo di apprendimento a motore fermo e `backtest learn`.
|
||||
|
||||
## Fermare
|
||||
|
||||
- **FERMA** nell'interfaccia, `stop` da console, `docker stop` (SIGTERM, 45 s di grazia), Ctrl+C. I basket aperti **restano sul conto** con gli stop nativi (`run.closeOnShutdown = false`): nessuno applica TP e stop di basket finché il bot non riparte, che li riprende dallo stato salvato e dalla riconciliazione (e, se è passato più di dieci minuti, con il recupero dopo inattività).
|
||||
- Con `run.closeOnShutdown = true` la fermata chiude tutto a mercato.
|
||||
- **FERMA** (⏻ verde, con conferma), `stop` da console, `docker stop` (SIGTERM, 45 s di grazia), Ctrl+C. I basket aperti **restano sul conto** con gli stop nativi (`run.closeOnShutdown = false`): nessuno applica TP e stop di basket finché il bot non riparte, che li riprende dallo stato del conto e dalla riconciliazione (e, se è passato più di dieci minuti, con il recupero dopo inattività).
|
||||
- Con «Chiudi i basket all'arresto» (`run.closeOnShutdown = true`) il motore, sul suo thread, blocca prima nuove entrate e aggiunte e poi chiude basket, gambe in attesa e orfane, al più in 30 s; poi si ferma comunque.
|
||||
- **FERMA durante un kill-switch, una chiusura o la chiusura dei residui** risponde 409 («kill-switch in corso…»): ripeti quando è concluso. Vale anche se la scheda che l'ha lanciato è stata chiusa, se la risposta è stata 504 dopo 120 s o se Telegram è stato spento nel frattempo: il motore lo porta a termine comunque. `docker stop` invece non aspetta oltre 30 s: un kill-switch ancora in corso viene interrotto, le posizioni del bot rimaste diventano il residuo (Halted-Residuo, riga `kill_switch_interrotto`) e al riavvio si chiudono con «Chiudi residui» o un nuovo kill-switch, poi il reset.
|
||||
- **AVVIA subito dopo FERMA** aspetta che il motore precedente abbia lasciato la cartella dati (lo stato resta «in arresto» per qualche secondo).
|
||||
|
||||
## Kill-switch
|
||||
|
||||
Tre modi: il pulsante **KILL-SWITCH** nella barra in alto (chiede conferma e, se ci sono posizioni esterne, se chiudere anche quelle: default no), `kill` da console o `/kill CONFERMO` da Telegram, oppure un file chiamato `STOP` nella cartella `/config` (controllato ogni 5 s; utile da remoto: `touch /mnt/user/appdata/encelado/config/STOP`). La procedura è la stessa per i tre e **non dichiara niente chiuso senza averlo riletto dal conto**:
|
||||
Quattro modi: il pulsante **KILL** nella barra in alto (attivo con il motore in esecuzione; chiede conferma, con il fuoco su «Annulla», e la casella «Chiudi anche le posizioni esterne»), `kill` da console, `/kill CONFERMO` da Telegram, oppure un file chiamato `STOP` nella cartella `/config` (controllato ogni 5 s; utile da remoto: `touch /mnt/user/appdata/encelado/config/STOP`). **Posizioni esterne**: la casella del dialogo parte uguale a «Il kill-switch chiude anche le posizioni esterne» (Impostazioni ▸ Strategia, spenta di fabbrica) e la scelta fatta lì è quella che succede; Telegram e il file `STOP` usano l'impostazione; la console chiede solo se ce ne sono. La procedura è la stessa per tutti e **non dichiara niente chiuso senza averlo riletto dal conto**:
|
||||
|
||||
1. blocco immediato di ogni nuova entrata, riga `kill_switch_avviato` nel ledger;
|
||||
1. blocco immediato di ogni nuova entrata, riga `kill_switch_avviato` nel ledger (con chi ha deciso sulle esterne);
|
||||
2. annullamento degli ordini nel registro senza esito (`DELETE …/orders/{id}`), poi attesa della loro risoluzione fino a 30 s: un ordine eseguito nel frattempo diventa una posizione da chiudere;
|
||||
3. chiusura di **tutte le posizioni del bot**: gambe dei basket (tre tentativi per gamba con verifica sul conto), gambe in attesa, orfane-bot; le posizioni esterne solo se lo hai chiesto o se `risk.closeForeignOnKill = true`;
|
||||
3. chiusura di **tutte le posizioni del bot**: gambe dei basket (tre tentativi per gamba con verifica sul conto), gambe in attesa, orfane-bot; le esterne secondo la scelta;
|
||||
4. verifica di piattezza: il conto viene riletto finché le posizioni del bot non sono sparite (fino a 120 s);
|
||||
5. riga `kill_switch_concluso` con l'esito, stato salvato, notifica.
|
||||
|
||||
Se qualcosa resta sul conto lo stato è **`Halted-Residuo`**: banner rosso con l'elenco, chip «bloccato · residuo», il reset è rifiutato finché non è piatto. Per riprovare: **Sblocca…** nel banner (il ripristino offre «Chiudi ora» sui residui), `residuo` da console (`residuo <id>` per una sola posizione), oppure chiusura a mano su eToro; la riconciliazione se ne accorge. Il blocco resta finché non fai un **reset**.
|
||||
Se qualcosa resta sul conto lo stato è **`Halted-Residuo`**: striscia rossa «Kill-switch con residuo» con **Chiudi residui**, il reset è rifiutato finché non è piatto. Per riprovare: «Chiudi residui», `residuo` da console (`residuo <id>` per una sola posizione), oppure chiusura a mano su eToro; la riconciliazione se ne accorge e un residuo che il conto non mostra più esce dall'elenco. Le gambe di un basket rimaste nel residuo diventano una riga sola di `baskets.csv`, come basket, quando sono tutte chiuse. Il blocco resta finché non fai un **reset**. Un kill-switch in corso non viene interrotto da FERMA né da un salvataggio delle impostazioni.
|
||||
|
||||
## Equity stop
|
||||
## Equity stop e perdita giornaliera
|
||||
|
||||
Quando l'equity (al netto dei movimenti di cassa) scende del 9 % dal picco (`equityStopPct`) il bot chiude tutto e si blocca: banner rosso nella dashboard, riga `equity_stop` nel ledger. Per ripartire serve il reset. La perdita giornaliera del 3 % (`dailyLossPct`) blocca solo le nuove entrate fino alla mezzanotte UTC e non richiede reset.
|
||||
Quando l'equity (al netto dei movimenti di cassa) scende del 9 % dal picco (`equityStopPct`) il bot chiude tutto e si blocca: striscia rossa, riga `equity_stop` nel ledger. Per ripartire serve il reset.
|
||||
|
||||
La **perdita giornaliera** del 3 % (`dailyLossPct`, sull'equity netta dalla mezzanotte UTC) blocca solo le nuove entrate e le aggiunte, **fino alle 00:00 UTC anche se l'equity recupera, anche dopo un riavvio**; non chiude niente e non richiede reset (D-52). La tessera della dashboard diventa rossa con l'ora di sblocco nel tuo fuso, la striscia degli allarmi lo dice e Telegram manda un avviso. Se il saldo cala per qualcosa che lo storico eToro non spiega ancora (forse un prelievo) le entrate restano sospese finché non si chiarisce, anche se nel frattempo l'equity recupera; quando lo storico lo spiega, se era una perdita e al minimo toccato nel frattempo l'equity netta era oltre la soglia la giornata si blocca fino alle 00:00 UTC, se era un movimento di cassa (prelievo o deposito) no.
|
||||
|
||||
## Ripristino (reset) in cinque passi
|
||||
|
||||
**Sblocca…** nel banner o **Avvia il ripristino…** in Impostazioni, `reset <motivazione>` da console, `/reset <motivazione>` da Telegram. Il reset è una procedura, non un interruttore; il dialogo mostra i cinque passi e l'esito di ciascuno, che finisce anche nel ledger:
|
||||
**Sblocca…** nella striscia degli allarmi o **Ripristino…** in Sistema, `reset <motivazione>` da console, `/reset <motivazione>` da Telegram. Il reset è una procedura, non un interruttore; il dialogo mostra i cinque passi e l'esito di ciascuno, che finisce anche nel ledger:
|
||||
|
||||
| Passo | Che cosa fa | Se fallisce |
|
||||
|---|---|---|
|
||||
| 1. stato | riporta il motivo del blocco, i residui, gli ordini senza esito, le entrate bloccate | — |
|
||||
| 2. file STOP | lo rimuove da solo; se ricompare il kill-switch riparte | «file STOP non rimovibile»: permessi della cartella `/config` (PUID/PGID) |
|
||||
| 3. motivazione | almeno dieci caratteri, scritta nel ledger come `correzione` | «motivazione mancante»: riscrivila |
|
||||
| 4. riconciliazione | rilegge il conto, verifica che nessuna posizione del bot sia rimasta, riscalda le serie dall'API, riporta il picco di equity all'equity corrente (al netto dei movimenti di cassa) | «residui ancora sul conto» → resta `Halted-Residuo` (riga `reset_rifiutato`): chiudili con «Chiudi ora» / `residuo` / a mano e ripeti |
|
||||
| 5. ripartenza | toglie il blocco; **entrate bloccate per 15 minuti** di riscaldamento (`riscaldamento dopo il reset` nel banner giallo), poi il bot riprende da solo | — |
|
||||
| 4. riconciliazione | rilegge il conto, verifica che nessuna posizione del bot sia rimasta, riscalda le serie dall'API, riporta il picco di equity all'equity corrente (al netto dei movimenti di cassa) | «residui ancora sul conto» → resta `Halted-Residuo` (riga `reset_rifiutato`): chiudili con «Chiudi residui» / `residuo` / a mano e ripeti |
|
||||
| 5. ripartenza | toglie il blocco; **entrate bloccate per 15 minuti** di riscaldamento (`riscaldamento dopo il reset` nella striscia), poi il bot riprende da solo | — |
|
||||
|
||||
Sintomo → passo:
|
||||
|
||||
| Sintomo | Passo da guardare |
|
||||
|---|---|
|
||||
| banner «KILL-SWITCH CON RESIDUO» | 4: chiudi i residui, poi ripeti il reset |
|
||||
| «Kill-switch con residuo» nella striscia | 4: chiudi i residui, poi ripeti il reset |
|
||||
| «rimuovi prima il file STOP» / «file STOP non rimovibile» | 2: `/config` non è scrivibile dall'utente del container o il file viene ricreato da un altro processo |
|
||||
| «motivazione mancante» | 3 |
|
||||
| dopo il reset il bot non apre per un quarto d'ora | 5: è il riscaldamento voluto |
|
||||
| dopo il reset compare «posizioni non riconciliate» | 4 non è andato a buon fine sul conto: confronta `pending_orders.json` e le posizioni su eToro (pagina Storico ▸ Posizioni) |
|
||||
| dopo il reset compare «posizioni non riconciliate» | 4 non è andato a buon fine sul conto: confronta `pending_orders.json` e le posizioni su eToro (pagina Posizioni) |
|
||||
|
||||
## Ordini senza esito
|
||||
|
||||
eToro lavora gli ordini in modo asincrono e a volte non risponde al lookup. Il bot non dimentica mai un ordine: ogni invio è scritto in `data/state/pending_orders.json` **prima** della chiamata, l'esito viene chiesto per `orderId` e, se il server non lo trova, ricostruito dalla posizione comparsa sul conto. Un basket con una gamba senza esito compare in dashboard come «attesa gamba A/B» e nel contatore «in attesa»: non manda altri ordini finché il registro non lo risolve. Alla risoluzione: gamba A eseguita e segnale ancora valido → parte la gamba B; segnale decaduto → la gamba A viene richiusa subito (`leg_risk_unwind`); rifiutata → il basket torna libero. Se un ordine resta senza esito per più di dieci minuti il log lo ripete ogni dieci minuti: guarda Storico ▸ Ordini (esito `Pending`) e, se serve, la posizione su eToro; non c'è niente da fare a mano finché la gamba non compare sul conto, e quando compare il bot la gestisce. All'avvio i pendenti del run precedente vengono risolti prima di qualsiasi decisione.
|
||||
eToro lavora gli ordini in modo asincrono e a volte non risponde al lookup. Il bot non dimentica mai un ordine: ogni invio è scritto in `data/state/pending_orders.json` **prima** della chiamata, con il suo conto; l'esito viene chiesto per `orderId` e, se il server non lo trova, ricostruito dalla posizione comparsa sul conto. Un basket con una gamba senza esito compare in dashboard come «Attesa A/B» e nel contatore «in attesa»: non manda altri ordini finché il registro non lo risolve. Alla risoluzione: gamba A eseguita e segnale ancora valido → parte la gamba B; segnale decaduto → la gamba A viene richiusa subito (`leg_risk_unwind`); rifiutata → il basket torna libero. Se un ordine resta senza esito per più di dieci minuti il log lo ripete ogni dieci minuti: guarda Storico ▸ Ordini (esito `Pending`) o Posizioni ▸ ordini in attesa e, se serve, la posizione su eToro; non c'è niente da fare a mano finché la gamba non compare sul conto, e quando compare il bot la gestisce. All'avvio i pendenti del conto vengono risolti prima di qualsiasi decisione; quelli dell'altro conto aspettano il suo motore.
|
||||
|
||||
## Riconciliazione
|
||||
|
||||
Ogni 20 secondi il bot rilegge conto e posizioni e **classifica ogni posizione**: `basket` (gamba nota), `orfana-bot` (aperta dal bot ma senza basket: id nel registro degli ordini, oppure strumento, verso e orario coerenti con una decisione del ledger entro 90 s), `esterna` (tutto il resto). Una gamba di basket sparita dal conto (chiusa a mano, stop nativo) fa chiudere l'altra; un'orfana-bot viene **adottata e chiusa** (riga `orfana_adottata` e `orfana_chiusa` nel ledger, riga in `baskets.csv` con `exit_reason = orphan_closed`; dopo tre tentativi falliti le entrate si bloccano e il banner lo dice: chiudila a mano su eToro); un'esterna viene segnalata una volta, contata e mai toccata. Una chiusura incompleta dopo tre tentativi mette il basket in stato `Error` e blocca le nuove entrate finché non è risolta sul conto. Se il P&L aperto del conto e quello delle posizioni non tornano per più di un minuto compare «posizioni non riconciliate»: di solito è un'esecuzione in corso; se persiste, confronta `pending_orders.json` con le posizioni su eToro.
|
||||
Ogni 20 secondi il bot rilegge conto e posizioni e **classifica ogni posizione**: `basket` (gamba nota), `orfana-bot` (aperta dal bot ma senza basket: id nel registro degli ordini, oppure strumento, verso e orario coerenti con una decisione del ledger entro 90 s), `esterna` (tutto il resto). Una gamba di basket sparita dal conto (chiusa a mano, stop nativo) fa chiudere l'altra; un'orfana-bot viene **adottata e chiusa** (righe `orfana_adottata` e `orfana_chiusa` nel ledger, riga in `baskets.csv` con `exit_reason = orphan_closed`; dopo tre tentativi falliti le entrate si bloccano e la striscia lo dice: chiudila a mano su eToro); un'esterna viene segnalata una volta, contata e mai toccata. Una chiusura incompleta dopo tre tentativi mette il basket in stato `Error` e blocca le nuove entrate finché non è risolta sul conto. Se il P&L aperto del conto e quello delle posizioni non tornano per più di un minuto compare «posizioni non riconciliate»: di solito è un'esecuzione in corso; se persiste, confronta `pending_orders.json` con le posizioni su eToro (pagina Posizioni).
|
||||
|
||||
Un deposito o un prelievo sul conto (anche l'accredito di fondi virtuali del demo) viene riconosciuto dal salto del saldo non spiegato dalle chiusure e scritto nel ledger come `movimento_di_cassa`: non è P&L, non muove il picco di equity né il drawdown; nello Storico compare come riga «movimento di cassa» e nei periodi è una colonna a parte.
|
||||
Un deposito o un prelievo sul conto (anche l'accredito di fondi virtuali del demo) viene riconosciuto dal salto del saldo non spiegato dalle chiusure e scritto nel ledger come `movimento_di_cassa`: non è P&L, non muove il picco di equity né il drawdown; nello Storico compare come riga «movimento di cassa» e nei periodi è una colonna a parte. Finché lo storico eToro non mostra una chiusura il saldo non viene giudicato, e all'avvio il saldo salvato si confronta solo quando lo storico mostra ogni posizione chiusa da allora: una chiusura in ritardo non diventa mai un prelievo.
|
||||
|
||||
## P&L oggi e realizzato
|
||||
|
||||
«P&L oggi» (dashboard, barra in alto, Telegram, console) è il **realizzato netto** (`netProfit − fees`) delle posizioni del bot chiuse nella giornata UTC, letto dallo storico di eToro: è lo stesso numero del periodo «oggi» della pagina Storico. Finché lo storico non conferma una chiusura il numero porta la sua **stima** (segnata «stima»); se lo storico non è ancora stato letto si vede «—», mai 0. Accanto c'è la variazione dell'equity netta da mezzanotte, che è ciò che guarda la perdita giornaliera. Ogni riga di `baskets.csv` porta il realizzato dello storico (motivazione «P&L: storico eToro»), oppure, se dopo 30 minuti lo storico non lo mostra ancora, la stima («P&L: stima…», che non addestra niente e viene ricontrollata a ogni avvio). Fino alla 5.0.0 il bot registrava come P&L i `proceeds` della chiusura (margine restituito più profitto): da lì il «P&L oggi» di circa 47 000 USD su 139 000; il ledger è corretto con righe nuove, i messaggi Telegram e i log di allora no (`docs/KNOWN_ISSUES.md`).
|
||||
|
||||
## Recupero dopo inattività (riavvio, aggiornamento dell'immagine, container fermo)
|
||||
|
||||
Il bot scrive `data/state/heartbeat.json` ogni 30 s (`recovery.heartbeatSeconds`). All'avvio legge quello precedente e a ogni ciclo misura il tempo dall'ultimo giro: oltre `recovery.thresholdMinutes` (10) parte il **recupero**, nell'ordine: entrate bloccate e riga `recupero_avviato`; ordini senza esito risolti; riconciliazione con classificazione (le orfane si chiudono, le esterne si riportano); serie riscaldate dall'API con le barre perse e `barsHeld` di ogni basket aperto aumentato delle barre trascorse; ogni basket aperto rivalutato come a una chiusura di barra ordinaria (stop di z, perdita massima, time-stop con le barre di inattività, correlazione rotta, spread anomalo): **chiudi** o **tieni**; rapporto `reports/recupero_<run_id>.csv` (una riga per posizione: `posizione;basket;decisione;motivo;z;rho;barsHeld;pnl;motivazione`), riga `recupero_concluso`, notifica; entrate riaperte dopo `recovery.warmupMinutes` (15) di quotazioni. Se il mercato è chiuso (fine settimana) il recupero aspetta le prime quotazioni fresche e lo dice ogni dieci minuti: niente di irreversibile a mercato chiuso. Un recupero fallito lascia le entrate bloccate con il motivo: guarda il log e fai un reset.
|
||||
Il bot scrive `data/state/heartbeat.json` ogni 30 s (`recovery.heartbeatSeconds`). All'avvio legge quello precedente e a ogni ciclo misura il tempo dall'ultimo giro: oltre `recovery.thresholdMinutes` (10) parte il **recupero**, nell'ordine: entrate bloccate e riga `recupero_avviato`; ordini senza esito risolti; riconciliazione con classificazione (le orfane si chiudono, le esterne si riportano); serie riscaldate dall'API con le barre perse e `barsHeld` di ogni basket aperto aumentato delle barre trascorse; ogni basket aperto rivalutato come a una chiusura di barra ordinaria (stop di z, perdita massima, time-stop con le barre di inattività, correlazione rotta, spread anomalo): **chiudi** o **tieni**; rapporto `reports/recupero_<run_id>.csv` (una riga per posizione: `posizione;basket;decisione;motivo;z;rho;barsHeld;pnl;motivazione`), riga `recupero_concluso`, notifica; entrate riaperte dopo `recovery.warmupMinutes` (15) di quotazioni. Lo stesso recupero parte per un conto i cui basket nessuno ha seguito oltre la soglia mentre il bot girava sull'altro. Se il mercato è chiuso (fine settimana) il recupero aspetta le prime quotazioni fresche e lo dice ogni dieci minuti: niente di irreversibile a mercato chiuso. Un recupero fallito lascia le entrate bloccate con il motivo: guarda il log e fai un reset.
|
||||
|
||||
## Telegram
|
||||
|
||||
Configurazione in `encelado.json` → `notifications.telegram` (`enabled`, `chatId`, `hourlyStatus`, `eventAlerts`, `dailySummaryUtcHour`, `commands`) e in Impostazioni → Notifiche. Il token del bot va **solo** nella variabile d'ambiente `TELEGRAM_BOT_TOKEN` (la chat in `TELEGRAM_CHAT_ID`, che ha la precedenza sul file). Per creare il bot: `@BotFather` → `/newbot` → token; per il chat id: scrivi al bot e leggi `chat.id` da `https://api.telegram.org/bot<token>/getUpdates`, oppure `@userinfobot`. Cosa arriva:
|
||||
Tutto da **Impostazioni ▸ Notifiche Telegram**: «Telegram attivo», il token del bot (verificato con `getMe` e cifrato in `secrets.enc`), la chat (`chatId`, la sola che riceve i messaggi e può dare comandi), «Stato ogni ora», «Eventi», l'ora del riepilogo giornaliero (UTC, negativo = spento), «Comandi dalla chat», e **Invia messaggio di prova**. Ogni cambio vale subito (il canale e il poller dei comandi si accendono, si spengono o cambiano senza riavvio). Per creare il bot: `@BotFather` → `/newbot` → token; per il chat id: scrivi al bot e leggi `chat.id` da `https://api.telegram.org/bot<token>/getUpdates`, oppure `@userinfobot`. Cosa arriva:
|
||||
|
||||
- **stato ogni ora** (allo scoccare dell'ora UTC): attivo/fermo/bloccato, modalità, preset, uptime, equity/saldo/disponibile/margine, P&L di oggi e aperto (conto e basket), drawdown dal picco, basket aperti con z/pip/P&L/durata, in attesa, ordini pendenti, orfane, esterne, blocchi, prossimo evento, stato API e quote, stato del canale;
|
||||
- **eventi**: avvio e arresto del bot, basket aperto e chiuso (con motivo e P&L), gamba in attesa, ordine pendente risolto, unwind, gamba orfana, kill-switch (con esito e residui), equity stop, perdita giornaliera, margin guard, recupero dopo inattività, reset, cambio preset, API in errore persistente, scarto orologio;
|
||||
- **riepilogo giornaliero** all'ora impostata (21 UTC): basket chiusi, vinti, lordo, costi, netto, drawdown, motivi di uscita.
|
||||
- **stato ogni ora** (allo scoccare dell'ora UTC): attivo/fermo/bloccato, modalità, preset, uptime, equity/saldo/disponibile/margine, P&L di oggi (dallo storico, «—» se sconosciuto) e aperto (conto e basket), drawdown dal picco, basket aperti con z/pip/P&L/durata, in attesa, ordini pendenti, orfane, esterne, blocchi, prossimo evento, stato API e quote, stato del canale;
|
||||
- **eventi**: avvio e arresto del bot, basket aperto e chiuso (il messaggio di chiusura arriva quando lo storico eToro conferma il P&L, o con la stima dopo 30 minuti), gamba in attesa, ordine pendente risolto, unwind, gamba orfana, kill-switch (con esito e residui), equity stop, perdita giornaliera («niente nuove entrate fino alle 00:00 UTC»), margin guard, recupero dopo inattività, reset, cambio delle impostazioni, Live da confermare, API in errore persistente, scarto orologio;
|
||||
- **riepilogo giornaliero** all'ora impostata (21 UTC): basket chiusi, vinti, lordo, costi, netto, drawdown, motivi di uscita (le righe non verificate sono escluse e contate a parte).
|
||||
|
||||
Comandi accettati **solo dalla chat autorizzata** (ogni altro mittente viene ignorato e annotato nel log; ogni comando eseguito finisce nel ledger come `comando`): `/stato`, `/posizioni`, `/storico 7d` (anche `1d`, `30d`), `/pausa` (blocca le entrate, le uscite restano attive), `/riprendi`, `/chiudi <basket>`, `/kill CONFERMO` (senza la parola non fa niente), `/reset <motivazione>` (almeno dieci caratteri); tutto il resto risponde «comando non riconosciuto». Il polling usa un solo task con `getUpdates` e non tocca le quote di eToro; gli invii sono al massimo uno al secondo con tre tentativi (2, 5, 15 s; su 429 rispetta `retry_after`). La card «Telegram» della dashboard e la riga di stato del log riportano lo stato del canale (ultimo invio, coda, falliti, ultimo errore).
|
||||
Comandi accettati **solo dalla chat autorizzata** (ogni altro mittente viene ignorato e annotato nel log; ogni comando eseguito finisce nel ledger come `comando`): `/stato`, `/posizioni`, `/storico 7d` (anche `1d`, `30d`), `/pausa` (blocca le entrate, le uscite restano attive; sopravvive a un riavvio), `/riprendi`, `/chiudi <basket>`, `/kill CONFERMO` (senza la parola non fa niente; le esterne secondo l'impostazione), `/reset <motivazione>` (almeno dieci caratteri); tutto il resto risponde «comando non riconosciuto». Il polling usa un solo task con `getUpdates` e non tocca le quote di eToro; gli invii sono al massimo uno al secondo con tre tentativi (2, 5, 15 s; su 429 rispetta `retry_after`). Sistema ▸ Telegram riporta lo stato del canale (configurato, inviati, in coda, falliti, ultimo invio, ultimo errore).
|
||||
|
||||
## Bonifica delle gambe orfane
|
||||
|
||||
Una tantum, dopo un'anomalia: **Impostazioni ▸ Diagnostica ▸ Bonifica: elenca le orfane** mostra ogni posizione del conto con origine, P&L e motivo della classificazione e offre **Chiudi** su ciascuna orfana-bot; oppure `--bonifica` all'avvio (il motore parte senza chiudere le orfane da solo e chiede `chiudere? [s/N]` da console) o `bonifica` da console. Ogni chiusura confermata scrive una riga in `baskets.csv` (`exit_reason = bonifica_orfana`, P&L dallo storico) e in `reports/bonifica_YYYYMMDD.csv`. Alla fine il bot torna a chiudere le orfane da solo. Al 2026-09-23 il conto demo è piatto: non c'è niente da bonificare.
|
||||
Una tantum, dopo un'anomalia: la pagina **Posizioni** mostra ogni posizione del conto con origine, P&L e motivo della classificazione e, quando ci sono orfane del bot, **Bonifica orfane** (una conferma per posizione); **Sistema ▸ Diagnostica ▸ Elenca le orfane** fa lo stesso elenco; oppure `--bonifica` all'avvio (il motore parte senza chiudere le orfane da solo e chiede `chiudere? [s/N]` da console) o `bonifica` da console. Ogni chiusura confermata scrive una riga in `baskets.csv` (`exit_reason = bonifica_orfana`, P&L dallo storico) e in `reports/bonifica_YYYYMMDD.csv`. Alla fine il bot torna a chiudere le orfane da solo.
|
||||
|
||||
## Apprendimento
|
||||
|
||||
La pagina **Apprendimento** mostra tutto ciò che il sistema sa (dataset, criteri di attivazione, pesi, bandit, ultimo ciclo, calibrazione, proposte; `docs/ML_AND_LEARNING.md`). **Esegui ciclo**:
|
||||
|
||||
- motore acceso: il ciclo parte in background e la pagina ne mostra la fase; il motore continua a lavorare e applica il risultato fra due tick;
|
||||
- motore fermo o in errore: manutenzione che prende il lock della cartella dati; **AVVIA risponde 409** finché dura, di solito pochi secondi;
|
||||
- rifiutato (409, con il motivo) con un ciclo già in corso, con il motore che si avvia (finché il ciclo di decisione non è partito) o si ferma, o con il lock tenuto da un altro processo.
|
||||
|
||||
`backtest learn` sulla cartella dati del bot prende lo stesso lock o si rifiuta con il nome di chi lo tiene: con il bot acceso si usa «Esegui ciclo». Niente di ciò che il ciclo propone cambia i parametri: le proposte vanno in `knowledge/proposals.csv` e passano dal forward test.
|
||||
|
||||
## Errori API
|
||||
|
||||
| Sintomo | Cosa fa il bot | Cosa fare |
|
||||
|---|---|---|
|
||||
| 401/403 | avvio fallito, "eToro ha rifiutato le chiavi" | rigenera le chiavi sul portale, reinseriscile da Impostazioni ▸ Chiavi eToro o nelle variabili del container |
|
||||
| 429 | rispetta `Retry-After`, rallenta | niente; se persiste alza `run.pollSeconds` |
|
||||
| 5 letture consecutive fallite | banner "entrate bloccate", uscite attive | aspetta; controlla rete e stato di eToro |
|
||||
| scarto orologio > 5 s | banner, entrate bloccate | sincronizza l'ora dell'host (il container eredita l'orologio) |
|
||||
| 401/403 da eToro | avvio fallito, «eToro ha rifiutato le chiavi» | rigenera le chiavi sul portale e reinseriscile da Impostazioni ▸ Conto |
|
||||
| «nessuna chiave eToro per il conto …» | il motore non parte | inserisci le chiavi di quel conto in Impostazioni ▸ Conto |
|
||||
| «segreti bloccati» | il motore non parte | Impostazioni ▸ Conto: sblocca con la password precedente o ricomincia |
|
||||
| 429 | rispetta `Retry-After`, rallenta | niente; se persiste alza «Lettura quotazioni ogni» (`run.pollSeconds`) |
|
||||
| 5 letture consecutive fallite | entrate bloccate, uscite attive | aspetta; controlla rete e stato di eToro |
|
||||
| scarto orologio > 5 s | allarme, entrate bloccate | sincronizza l'ora dell'host (il container eredita l'orologio) |
|
||||
| quotazioni più vecchie di 15 s | niente nuove entrate | come sopra |
|
||||
| `/api/health` rosso (`docker inspect`) | il container viene riavviato da `--restart` se il processo muore; un healthcheck rosso con processo vivo dice cosa manca (heartbeat vecchio, disco non scrivibile) | `docker logs`, poi `docker restart` |
|
||||
| storico eToro illeggibile | «P&L oggi» resta «—» o con le stime; le chiusure aspettano in coda; nessun saldo giudicato | niente; se dura ore controlla la quota Default in Sistema |
|
||||
| `/api/health` rosso (`docker inspect`) | il container viene riavviato da `--restart` se il processo muore; un healthcheck rosso con processo vivo dice cosa manca (heartbeat più vecchio di 3 × `recovery.heartbeatSeconds` + 15 s, 105 s di fabbrica; disco non scrivibile) | `docker logs`, poi `docker restart`; un kill-switch lungo può far risultare il container non sano per qualche minuto |
|
||||
|
||||
Sistema mostra il dettaglio: stato del motore, collegamento eToro con latenza, scarto e quote (con i 429 e l'ultimo errore), feed, Telegram, segreti, processo, disco, log.
|
||||
|
||||
## Feed
|
||||
|
||||
Calendario e notizie sono in cache su disco (`data/cache`) e vengono riletti ogni 10 minuti con attese crescenti dopo un errore. Un feed che non risponde non ferma il bot: senza calendario non c'è blackout, senza notizie il sentiment è 0, e il log lo dice. Google News blocca via `robots.txt` le ricerche RSS: quelle fonti vivono solo di cache (vedi `docs/DATA_SOURCES.md`).
|
||||
Calendario e notizie sono in cache su disco (`data/cache`) e vengono riletti **in background** ogni 10 minuti, con attese crescenti dopo un errore; il ciclo di decisione non li aspetta mai, e il processo li tiene aggiornati anche a motore fermo. Un feed che non risponde non ferma il bot: senza calendario non c'è blackout, senza notizie il sentiment è 0, e il log lo dice. Sistema ▸ Feed mostra lo stato di ogni fonte. Google News blocca via `robots.txt` le ricerche RSS: quelle fonti vivono solo di cache (vedi `docs/DATA_SOURCES.md`).
|
||||
|
||||
## Storico
|
||||
|
||||
**Storico ordini** nell'interfaccia: *Ordini* da `orders.jsonl` (unità richieste ed eseguite — se differiscono il server ha ridotto l'ordine —, prezzi, slippage, stato, esito, id di ordine e posizione), *Posizioni* dallo storico eToro classificate per origine, *Profitti per periodo* con la curva dell'equity realizzata. Ogni vista si esporta in CSV (`;`, colonna `motivazione`). Senza chiavi la pagina mostra solo i dati del ledger e lo dice.
|
||||
Pagina **Storico**: *Ordini* da `orders.jsonl` (unità richieste ed eseguite — se differiscono il server ha ridotto l'ordine —, prezzi, slippage, stato, esito, id di ordine e posizione), *Posizioni* dallo storico eToro classificate per origine, *Profitti per periodo* con la curva del realizzato. Ogni vista si esporta in CSV (`;`, colonna `motivazione`). Senza chiavi la pagina mostra solo i dati del ledger e lo dice.
|
||||
|
||||
## File utili
|
||||
|
||||
| Cosa | Dove (container) |
|
||||
|---|---|
|
||||
| log | `/data/logs/encelado.log` (CSV `;`) e `docker logs` |
|
||||
| ledger | `/data/data/ledger/decisions.jsonl`, `baskets.csv`, `orders.jsonl` |
|
||||
| stato | `/data/data/state/baskets_state.json` (ripreso all'avvio), `pending_orders.json` (registro degli ordini), `heartbeat.json`, `instance.lock` |
|
||||
| ledger | `/data/data/ledger/decisions.jsonl` (e i mesi ruotati `decisions_YYYYMM.jsonl`), `baskets.csv`, `orders.jsonl` |
|
||||
| stato | `/data/data/state/baskets_state.demo.json` e `baskets_state.live.json` (uno per conto, ripreso all'avvio; il vecchio `baskets_state.json` resta come `.migrato`), `pending_orders.json` (registro degli ordini dei due conti), `heartbeat.json`, `instance.lock` |
|
||||
| barre | `/data/data/market/candles_<SYMBOL>_M15.csv` |
|
||||
| modelli | `/data/data/models/` |
|
||||
| modelli | `/data/data/models/` (con `last_cycle.json`, `learning_state.json`, `ritirati/`) |
|
||||
| conoscenza | `/data/knowledge/` |
|
||||
| rapporti | `/data/reports/` (qualità dati, bonifica, recupero) |
|
||||
| configurazione, strumenti, chiavi, STOP | `/config/encelado.json`, `strategy.json`, `instruments.json`, `etoro.keys.enc`, `STOP` |
|
||||
| configurazione, strumenti, segreti, STOP | `/config/encelado.json`, `strategy.json`, `instruments.json`, `secrets.enc`, `import-5.1.json`, `STOP` |
|
||||
|
||||
Fuori dal container gli stessi percorsi stanno sotto `Documenti\Encelado` (`data\…`, `knowledge\…`, `logs\…`).
|
||||
Fuori dal container gli stessi percorsi stanno sotto la sandbox `deploy/local/` (`config/`, `data/`) o `Documenti\Encelado`.
|
||||
|
||||
## Checklist prima del Live (§9.4 della specifica)
|
||||
|
||||
Tutte vere, altrimenti no:
|
||||
|
||||
- [ ] il forward test in Demo ha almeno 60 basket chiusi e 90 giorni;
|
||||
- [ ] il P&L netto del forward test è positivo con PSR ≥ 0,95 sulla metrica pre-registrata in `knowledge/preregistrazione.csv`;
|
||||
- [ ] il P&L netto del forward test (realizzato dello storico eToro) è positivo con PSR ≥ 0,95 sulla metrica pre-registrata in `knowledge/preregistrazione.csv`;
|
||||
- [ ] nessun test di falsificazione contraddice il risultato (oggi `reports/falsificazione.csv` dice il contrario: vedi `docs/STRATEGY.md`);
|
||||
- [ ] `run.allowLive = true`, ambiente `real`, chiavi del reale inserite e verificate;
|
||||
- [ ] chiavi del conto reale inserite e verificate in Impostazioni ▸ Conto, «Consenti il conto reale» acceso, conto `Live` (il cambio richiede il conto demo piatto);
|
||||
- [ ] conto reale capiente rispetto a `riskPerBasketPct` e all'esposizione minima di 1000 USD per gamba (con 224,90 USD non lo è);
|
||||
- [ ] la frase `CONFERMO LIVE` scritta all'avvio (dialogo o `ENCELADO_CONFIRM_LIVE`).
|
||||
- [ ] la frase `CONFERMO LIVE` scritta nel dialogo di AVVIA, ogni volta: il Live non riparte mai da solo dopo un riavvio.
|
||||
|
||||
## Aggiornare
|
||||
|
||||
`docker pull` dell'immagine nuova e riavvio del container (su Unraid: *Controlla aggiornamenti*). `/config` e `/data` restano; il riavvio è un'inattività come le altre e passa dal recupero. Se dopo un aggiornamento il log segnala una configurazione di una versione precedente, da Impostazioni → **Ripristina i valori predefiniti** (backup automatico con la data accanto al file) e poi rimetti i valori tuoi.
|
||||
`docker pull` dell'immagine nuova e riavvio del container (su Unraid: *Controlla aggiornamenti*). `/config` e `/data` restano; il riavvio è un'inattività come le altre e passa dal recupero (in Live il motore resta fermo fino ad AVVIA con la frase). Dalla 5.0 alla 5.1 vedi «Aggiornare un container 5.0 alla 5.1» qui sopra e `deploy/unraid/README.md`. Se dopo un aggiornamento il log segnala una configurazione di una versione precedente, da Impostazioni ▸ Valori predefiniti **Ripristina** (backup automatico con la data accanto al file, a motore fermo) e poi rimetti i valori tuoi.
|
||||
@@ -1,32 +1,44 @@
|
||||
# Stato del lavoro
|
||||
|
||||
Aggiornato: 2026-09-23 (sessione 5.0, Fasi 6-9 concluse: il piano 5.0 è completo).
|
||||
Aggiornato: 2026-10-01 (5.1.0 completata nel codice e nei documenti; da spingere, rilasciare e provare sul conto demo).
|
||||
|
||||
## Fase in corso
|
||||
|
||||
**Piano 5.0 concluso** (`docs/PIANO_5.0.md`): tutte le fasi 0-9 sono fatte. Il bot è `Encelado.Server` (Kestrel + motore + interfaccia web incorporata) e gira nel container (ADR-0007, ADR-0008); la finestra WPF non esiste più (D-28). Versione di sviluppo 5.0.0 in `Directory.Build.props`; **il rilascio 5.0.0 non è ancora stato fatto** (tag, immagine sul registro di Gitea, release): lo decide l'utente con `dotnet msbuild build/Release.proj -t:Rilascia -p:Versione=5.0.0` dopo il push del ramo.
|
||||
**5.1 conclusa nel repository.** Le richieste dell'utente di `Modifiche.txt` del 2026-09-30 sono implementate (solo la password nel container, tutto dall'interfaccia e applicato a caldo, Paper eliminata, «P&L oggi» corretto dallo storico eToro, nuova interfaccia in stile Mimante con la pagina Apprendimento, orologi con le bandiere, log su una riga), poi una revisione completa del codice ha trovato 51 problemi e i confermati sono corretti. Versione di sviluppo **5.1.0** (`Directory.Build.props`). Una seconda verifica indipendente delle correzioni ha trovato nove punti ancora aperti, corretti anche loro; la verifica finale prima del rilascio è passata. Build 0 avvisi, 0 errori; **561 test verdi**. Decisioni in ADR-0010…ADR-0014; scelte fatte senza risposta in `docs/QUESTIONS.md` D-38…D-58, **in attesa di conferma del proprietario**.
|
||||
|
||||
## Fatto nell'ultima sessione (2026-09-23, Fasi 6-9)
|
||||
**Non ancora fatto**: push del ramo, immagine 5.1.0 sul registro di Gitea e release (l'utente l'ha chiesto: «pusha il codice, crea l'immagine e caricala nella repository»), installazione su Unraid e prova sul conto demo. L'ultimo rilascio pubblicato resta la 5.0.0 (2026-09-23).
|
||||
|
||||
- **Fase 6 — Engine + Server**: `src/Encelado.Bot` → `src/Encelado.Engine` (libreria, senza UI); `src/Encelado.Server` (Sdk.Web, nessun NuGet) con `WebHost` (token in cookie HttpOnly o Bearer, senza token solo localhost), API JSON scritta a mano, SSE `/api/stream` a uno snapshot al secondo, `LogBuffer`, `HistoryService`; chiavi da variabili o file cifrato `etoro.keys.enc` (AES-256-GCM, `ENCELADO_KEY_PASSPHRASE`) al posto di DPAPI; `AppPaths` con `/config` e `/data`; `HeadlessRunner` ridotto a console (stato, comandi, bonifica); `--sample`, `--health`, `--no-autostart`, `ENCELADO_AUTOSTART`, `ENCELADO_CONFIRM_LIVE`.
|
||||
- **Fase 7 — interfaccia web Material 3** (`Web/wwwroot`, vanilla): navigation rail 80/256 px (drawer sotto 600 px), barra con orologi UTC e fuso, selettore della valuta (USD, EUR, GBP, CHF, JPY, AUD, CAD, NZD con tasso dalle quotazioni e tooltip in USD), AVVIA/FERMA, KILL-SWITCH con «chiudi anche le esterne»; dashboard con sei KPI (incluso il margine), tabella dei basket (cards da telefono), card evento/eToro/Telegram, attività, banner; **Storico ordini** (ordini, posizioni classificate, profitti per periodo con curva SVG, CSV); Log con filtri; Impostazioni con configurazione validata, chiavi eToro, ripristino in cinque passi, Ricerca, Diagnostica (con bonifica), Informazioni (versione, build, commit da `AssemblyMetadata`); temi scuro/chiaro. `HistoryBuilder` nel Core; `SnapshotJson`, `SampleSnapshot`, `SettingsService` nell'Engine; comando `learn` nello strumento (`Learn.cs`); `ui.displayCurrency/theme/navExpanded` e coppie di conversione nel polling.
|
||||
- **Fase 8 — Docker e Unraid**: `Dockerfile` multi-stage (build, **test**, publish, runtime `aspnet:10.0` + gosu + tzdata), `deploy/docker/entrypoint.sh` (TZ, PUID/PGID), `docker-compose.yml`, `.dockerignore`, `HEALTHCHECK --health`; `deploy/unraid/encelado.xml` (Container v2, icona `assets/encelado.png` raw da Gitea, D-29) e README; `build/Release.proj` senza Inno Setup: `Pubblica` framework-dependent, `Docker`, `Pacchetto` (zip + template + tag), `Rilascia` (push dell'immagine sul registro di Gitea + release); VS Code con F5 sul server (`Encelado (server)`, `Encelado (campione)`, backtest) e attività Docker. Immagine `192.168.30.23:3000/alby96/encelado:5.0.0` (346 MB) costruita dalla catena (`-t:Docker -p:Versione=5.0.0`, senza tag) con 210 test verdi nello stadio Linux e provata: avvio, semina di `/config`, permessi 99:100, `/api/health`, token, sonda `--health`, nessun avviso di Kestrel o di `useradd`. Il primo arresto con `docker stop` **non** era pulito (SIGKILL dopo la grazia): corretto con `PosixSignalRegistration` per SIGTERM in `Program.cs` e **verificato**: `docker stop` chiude in 1 s con «SIGTERM: arresto» ed exit 0.
|
||||
- **Avvio in locale (richiesta dell'utente)**: sandbox `deploy/local/` (`config/` = `/config`, `data/` = `/data`, ignorata da git) usata da F5 (`Encelado (server)`, `ENCELADO_CONFIG_DIR` + `ENCELADO_DATA_DIR`, che ora vale anche fuori dal container), dagli script `scripts/run-dev.ps1|.sh`, `run-docker.ps1|.sh` (compose, token `sviluppo`), `screenshots.ps1|.sh` e dalle attività di VS Code (`avvia in locale (script)`, `avvia in docker`, `ferma docker`, `screenshot`); provati tutti e tre i modi e lo script degli screenshot. `/api/health` in `--sample` non finge più un motore acceso.
|
||||
- **Fase 9 — documenti e pulizia**: ADR-0007, ADR-0008, `docs/DOCKER.md`, `docs/UI_GUIDELINES.md`, `README.md` con gli screenshot (`docs/img/`), `CLAUDE.md`, ARCHITECTURE, RUNBOOK, KNOWN_ISSUES, GLOSSARY, DATA_SOURCES, ML_AND_LEARNING, QUESTIONS (D-28, D-29, D-36, D-37 risposte), POSTMORTEM (gli «accrediti» erano crediti demo per ogni ordine ridotto), skill aggiornate, `build/README.md`. **Codice morto rimosso**: progetto WPF, DPAPI, test WPF, `UiRenderTests`, ~45 membri mai usati (statistiche di ricerca, `Psi`, `EmptyContextProvider`, `EnvironmentKeyStore`, display helper dello snapshot, `INotifyPropertyChanged` in `SettingField`, …). Test nuovi: `EmbeddedUiTests`, `WebHostTests`, `HistoryBuilderTests`, `KeyStoreTests`; suite a **210 verdi**.
|
||||
## Fatto nell'ultima sessione (2026-09-30 / 2026-10-01)
|
||||
|
||||
Commit in ordine (tutti su `main`, non spinti):
|
||||
|
||||
- `9cb5882` — **realizzato dallo storico eToro**: `proceeds` mai P&L, coda di regolamento persistente, «P&L oggi» dallo storico con le stime provvisorie, perdita giornaliera sull'equity netta, verifica del realizzato all'avvio con righe `correzione`, `lastNOutcomes` neutralizzata, modelli ritirati e logistica riaddestrata (ADR-0011).
|
||||
- `9875ab6` — **configurazione dall'interfaccia**: `ENCELADO_PASSWORD` e cookie HMAC, `secrets.enc` cifrato con la password, importazione una tantum dalla 5.0, Paper eliminata e modalità = conto, cancello Live senza variabili e mai automatico, preset fisso, applicazione a caldo (`SettingsRuntime`, comando `ApplySettings`, riavvio automatico senza chiudere i basket), template/compose/Dockerfile con la sola password (ADR-0010).
|
||||
- `58d5ea7` — **viste pubblicate e tick condiviso**: `EngineView` immutabile, `SnapshotHub` (un tick v2 al secondo per tutti), sezioni a richiesta con `ETag`, feed in background, dati d'esempio per ogni rotta (ADR-0012).
|
||||
- `50eb330` — **pagina Apprendimento** (`/api/learning`) e ciclo in background con un solo scrittore dei file, correzioni dell'apprendimento (ADR-0014).
|
||||
- `fef00c5` — **nuova interfaccia in stile Mimante**, verificata sul server vero; screenshot rifatti (ADR-0013).
|
||||
- Revisione: `07a00cd` (ciclo di vita: un lucchetto, nessun comando senza risposta, chiusura all'arresto sul thread di decisione), `b80638d` (interfaccia: kill-switch che fa ciò che si sceglie, impostazioni, stati dei basket spenti, `labels.js`), `c618f9f` (conti: stato per conto, guardia del cambio di conto nel motore, saldo all'avvio), `28db770` (rotazione del ledger solo in avanti), `7e3ace4` (soldi: perdita giornaliera fino a mezzanotte, una posizione una riga, verifica per conto, preset d'ingresso, scelta esplicita sulle esterne), `2d59c4e` (segreti e web: Live+demo resta demo, attesa dopo password errata anche per Bearer e cookie, richieste da altri siti rifiutate, `--sample` isolato, rete solo nel container), `54504ab` (apprendimento: contributi che spiegano la p, ritiro tutto o niente, conteggio dal dataset, ultima lettura buona, bracci mai provati).
|
||||
- `dcb274e` — **Documenti**: versione 5.1.0; ADR-0010…ADR-0014 e ADR-0005/0006/0007/0008 segnati come superati in parte; QUESTIONS D-38…D-58 (D-31 superata); README, CLAUDE.md, RUNBOOK, DOCKER, guida Unraid (installazione e aggiornamento dalla 5.0 passo per passo), ARCHITECTURE, GLOSSARY, KNOWN_ISSUES, LEDGER_SCHEMA, DATA_SOURCES, RISK_RULES, STRATEGY, ML_AND_LEARNING, UI_GUIDELINES, API (quotazioni nullable, risposte 400/500 dopo un riavvio fallito), skill di progetto; CHANGELOG 5.1.0.
|
||||
- `1cbd5a8` — **Seconda revisione**: lo stato della 5.0 va al conto su cui operava la 5.0 (`legacyState` registrato dall'importazione; Paper non ripreso); i comandi critici tengono fermi FERMA e i riavvii finché il motore li ha in mano, non finché il chiamante aspetta; le chiavi salvate mentre il conto cambia decidono il riavvio sul conto in uso dopo la verifica; la guardia del cambio di conto riconcilia prima di contare; la perdita giornaliera con lo storico in ritardo resta sospesa fino alla spiegazione e si blocca sul minimo se era una perdita; il secondo conto che corregge righe della 4.0-5.0 rimaschera `lastNOutcomes` e rifà la logistica; la pagina Apprendimento a motore fermo non chiama più «ultima lettura buona» i valori iniziali; il cookie di sessione contiene un segreto del server (`/config/session.key`) e non è più un tentativo di password (una scheda vecchia non tiene fuori la password giusta); test del preset d'ingresso rafforzati. Documenti, API e CHANGELOG aggiornati.
|
||||
- **Verifica finale prima del rilascio** (questo commit): build 0 avvisi, 0 errori; 561 test verdi, anche nella cartella di `Verifica` della catena; le classi di concorrenza e web ripetute due volte. Server vero su una sandbox con password: login con il cookie, `/api/settings` 401 senza sessione, scrittura in `text/plain` 415 e da un'altra origine 403 con il file intatto, in JSON accettata e subito nel tick, AVVIA senza chiavi rifiutato in italiano, arresto pulito (codice 0). Server `--sample`: 50 rotte GET a 200, le 12 scritture 400 «modalità dimostrativa», cartella temporanea cancellata all'uscita. Le nove pagine in Edge senza errori, eccezioni né scorrimento orizzontale a 1440 e 420 px; screenshot rifatti. `docs/API.md` confrontato campo per campo con il JSON vero; aggiunto `/logout` fra le rotte libere (anche in UI_GUIDELINES). Due controlli nuovi in `EmbeddedUiTests`: ogni icona usata esiste, e solo `api()` chiama il server e manda JSON a ogni scrittura.
|
||||
|
||||
## Prossimi passi
|
||||
|
||||
1. **Rilascio 5.0.0** (utente): push del ramo, `-t:Rilascia -p:Versione=5.0.0` (richiede Docker acceso, `build/gitea.json` con permesso `package`, registro `192.168.30.23:3000` dichiarato `insecure-registry`), poi installazione su Unraid dal template.
|
||||
2. Riaccendere il Demo nel container per 24 ore di verifica: contatore «orfane» a 0, `orders.jsonl` senza `Unknown` irrisolti, `sizing_bound = margin` sui primi ingressi; kill-switch a mano con verifica di piattezza; fermare il container un'ora con un basket aperto per vedere il recupero; messaggi Telegram reali.
|
||||
3. Revisione visiva dell'interfaccia con l'utente (gli screenshot sono dal campione `--sample`); eventuali ritocchi ai testi e ai tooltip.
|
||||
4. Avviso Telegram sui feed fermi da più di un'ora (resta in KNOWN_ISSUES).
|
||||
5. Rifare il backtest (`backtest baskets`) con i limiti di margine e aggiornare §3 di `docs/STRATEGY.md`.
|
||||
1. **Rilascio 5.1.0** (richiesta dell'utente): push di `main`, poi `dotnet msbuild build/Release.proj -t:Rilascia -p:Versione=5.1.0` (immagine `192.168.30.23:3000/alby96/encelado:5.1.0` e `:latest` sul registro di Gitea, tag `v5.1.0`, release con lo zip e il template). Serve Docker con qualche GB libero sul disco C:.
|
||||
2. **Aggiornare il container su Unraid** seguendo `deploy/unraid/README.md` §5: variabili tenute al primo avvio, `ENCELADO_WEB_TOKEN` rinominata `ENCELADO_PASSWORD` con lo stesso valore, poi variabili tolte; controllare nel log l'importazione, la migrazione dello stato, la verifica del realizzato e il ritiro dei modelli; «Esegui ciclo»; proposte nate dai proceeds segnate `respinta`.
|
||||
3. **Il proprietario conferma o corregge D-38…D-58** (`docs/QUESTIONS.md`), in particolare D-52 (blocco della perdita giornaliera fino a mezzanotte), D-53 (stato per conto), D-55 (scelta esplicita sulle esterne), D-56/D-57 (accesso e rete).
|
||||
4. **Prova sul conto demo** (24 ore): «P&L oggi» uguale al periodo «oggi» dello Storico e alla somma `netProfit − fees` dello storico eToro; righe di `baskets.csv` con «P&L: storico eToro»; contatore «orfane» a 0; `orders.jsonl` senza `Unknown` irrisolti; `sizing_bound = margin` sui primi ingressi; kill-switch a mano con verifica di piattezza; FERMA durante un kill-switch (409); cambio Demo → Live rifiutato con un basket aperto; container fermato un'ora con un basket aperto per il recupero; messaggi Telegram reali; revisione visiva dell'interfaccia con l'utente.
|
||||
5. **Runner di Gitea Actions** (act_runner su Unraid) e segreto `REGISTRY_TOKEN`, se si vuole che `ci.yml` e `release.yml` girino da soli (`docs/DOCKER.md`).
|
||||
6. Rifare il backtest (`backtest baskets`, `backtest falsify`) con i limiti di margine e il blocco della perdita giornaliera, e aggiornare §3 di `docs/STRATEGY.md`.
|
||||
7. Dai problemi aperti della revisione (`docs/KNOWN_ISSUES.md`): gamba aperta e chiusa fra due riconciliazioni giudicata movimento di cassa; kill-switch interni (file STOP, equity stop) non protetti da FERMA; heartbeat fermo durante comandi lunghi; `costPips` a 0 nel vettore valutato dal modello vivo; ingresso completato dopo un riavvio senza vettore; `exit_reason` delle chiusure all'arresto; compressione dei file statici.
|
||||
|
||||
## Problemi aperti
|
||||
|
||||
- Il disco C: del PC di sviluppo si era riempito (0 byte) a metà sessione; ora ha 12 GB liberi. Le immagini e la cache di build di Docker pesano: `docker system prune` ogni tanto.
|
||||
- Backtest negativo: la strategia non regge i costi (`docs/STRATEGY.md`).
|
||||
- Backtest negativo: la strategia non regge i costi (`docs/STRATEGY.md`); i numeri vanno rifatti con le regole della 5.0-5.1.
|
||||
- Il conto reale vale 224,90 USD: il Live non è praticabile.
|
||||
- Google News blocca le ricerche RSS; RBA 403 a intermittenza; Fed 404 a tratti.
|
||||
- Il server non ha TLS e il registro di Gitea è in HTTP (rete locale).
|
||||
- Il server non ha TLS e il registro di Gitea è in HTTP (rete locale); Gitea Actions senza runner.
|
||||
- I messaggi Telegram e i log della 4.0.0-5.0.0 con i proceeds come P&L non si possono correggere (il ledger sì).
|
||||
- Le righe del ledger della 5.0 scritte in `Live` con `etoro.environment` demo (o `Demo` con `real`) portano la modalità, non il conto: la verifica del realizzato le cerca sul conto sbagliato (`docs/KNOWN_ISSUES.md`). Con la configurazione di fabbrica della 5.0 non succede.
|
||||
- Il disco C: del PC di sviluppo è quasi pieno: le immagini e la cache di build di Docker pesano (`docker system prune` prima del rilascio).
|
||||
- `Modifiche.txt` nella radice è un appunto dell'utente, modificato e non committato: decidere se tenerlo nel repository.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Strategia: Correlation Baskets
|
||||
|
||||
Aggiornato: 2026-09-16. Questo documento dice come funziona la strategia e, con i numeri, **se regge**. La risposta sui dati disponibili è **no**: nessuna configurazione è profittevole al netto dei costi di eToro. Il modulo resta uno strumento di forward test in Demo; non c'è nessun risultato che giustifichi il reale.
|
||||
Aggiornato: 2026-10-01 (5.1: preset fisso in Impostazioni, perdita giornaliera bloccata fino alla mezzanotte UTC anche nel backtest; i numeri di §3 sono quelli del 2026-09-16 e vanno rifatti, vedi sotto). Questo documento dice come funziona la strategia e, con i numeri, **se regge**. La risposta sui dati disponibili è **no**: nessuna configurazione è profittevole al netto dei costi di eToro. Il modulo resta uno strumento di forward test in Demo; non c'è nessun risultato che giustifichi il reale.
|
||||
|
||||
## 1. Logica
|
||||
|
||||
@@ -18,7 +18,7 @@ In tutti e cinque la valuta comune ha ruoli opposti nelle due coppie, quindi `X
|
||||
|
||||
**Segnale** (`ZScoreSynthetic`): `z = (X − media_W) / σ_W` su W = 100 barre M15. Ingresso quando `|z| ≥ z_in` (2,0 nel preset Moderate), venduto il cross se z > 0, comprato se z < 0. Modalità alternativa `PipDivergence`: divergenza in pip fra le due gambe dall'ultimo punto di allineamento.
|
||||
|
||||
**Cancelli all'ingresso** (§5.3): correlazione rolling `ρ_W ≤ −0,6`, semiperiodo fra 5 e 120 barre, forza di trend sotto soglia, blackout del calendario, fine settimana, cost gate (`TP ≥ 3 × costo`, spread ≤ 2 × mediana 24 h), massimo di basket aperti, un solo basket per cross sintetico, quote fresche, orologio allineato, nessun blocco attivo.
|
||||
**Cancelli all'ingresso** (§5.3): correlazione rolling `ρ_W ≤ −0,6`, semiperiodo fra 5 e 120 barre, forza di trend sotto soglia, blackout del calendario, fine settimana, cost gate (`TP ≥ 3 × costo`, spread ≤ 2 × mediana 24 h), massimo di basket aperti, un solo basket per cross sintetico, quote fresche, orologio allineato, nessun blocco attivo. Fra i blocchi, la **perdita giornaliera** (3 % dell'equity netta di inizio giornata): raggiunta una volta, niente nuove entrate né aggiunte fino alle 00:00 UTC anche se l'equity recupera, dal vivo e nel backtest (D-52, `docs/RISK_RULES.md`).
|
||||
|
||||
**Sizing** (vol-parity): unità inversamente proporzionali all'ATR di ogni gamba, rischio totale alla distanza dello stop = `riskPerBasketPct` dell'equity (0,5 % Moderate), esposizione minima di eToro 1000 USD per gamba, leva effettiva ≤ 10. **Dalla 5.0** la size è il minimo fra quella a rischio e quella a margine (`risk` in `strategy.json`: 12 % dell'equity per basket, 40 % in totale, disponibile con buffer del 25 %): il 16/9 un solo basket sizato a rischio aveva impegnato il 100 % del margine. Il backtest applica gli stessi limiti dalla 5.0; i numeri di §3 sono della 4.0.0 (senza limite di margine) e vanno rifatti prima di trarne altre conclusioni: con meno nozionale il P&L per basket si riduce in valore assoluto, il segno del verdetto no.
|
||||
|
||||
@@ -26,7 +26,7 @@ In tutti e cinque la valuta comune ha ruoli opposti nelle due coppie, quindi `X
|
||||
|
||||
**Averaging** (§5.5): spento di fabbrica; `AddOnce` e `Grid` esistono solo per il test di falsificazione 2.
|
||||
|
||||
I preset (`strategy.json`):
|
||||
I preset (`strategy.json` → `preset`, scelto in Impostazioni ▸ Strategia; dalla 5.1 è fisso: non si cambia a caldo, e un cambio vale per i basket nuovi, mentre quelli aperti tengono z di stop, aggiunte, TP e perdita massima con cui sono entrati; le sovrascritture dei singoli numeri stanno in Strategia ▸ avanzate):
|
||||
|
||||
| Preset | z_in | rischio/basket | basket max | TP pip | aggiunte | z_stop |
|
||||
|---|---|---|---|---|---|---|
|
||||
@@ -41,7 +41,7 @@ I preset (`strategy.json`):
|
||||
- Due scenari di costo, entrambi assunzioni:
|
||||
- **etoro**: spread minimo per coppia = spread tipico pubblicato da eToro (EURUSD 1,0, USDCHF 1,5, AUDUSD 1,0, USDCAD 1,5, NZDUSD 2,5, EURNZD 5,0, EURAUD 3,0, AUDCAD 3,0 pip), overnight 0,3 pip/gamba/giorno;
|
||||
- **api**: spread dei tick senza pavimento (0,1-0,7 pip, come mostra l'API demo), overnight **0,9 pip/gamba/giorno** (0,91 USD/giorno per 10 000 EURUSD letti dall'endpoint dei costi il 2026-09-16).
|
||||
- Capitale iniziale 10 000 USD; equity stop al 9 % con ripartenza del picco (D-18), contando gli stop.
|
||||
- Capitale iniziale 10 000 USD; equity stop al 9 % con ripartenza del picco (D-18), contando gli stop. Dalla 5.1 la perdita giornaliera del backtest è la stessa del motore: raggiunta, blocca le entrate fino alla mezzanotte UTC (`ReplayDailyLoss`; prima si rivalutava a ogni decisione). I numeri di §3, fatti prima di questo blocco e dei limiti di margine della 5.0, vanno rifatti con `backtest baskets` e `backtest falsify`.
|
||||
- Niente calendario né notizie nel backtest: blackout e sentiment agiscono solo dal vivo.
|
||||
|
||||
## 3. Risultati
|
||||
|
||||
@@ -1,86 +1,375 @@
|
||||
# Linee guida dell'interfaccia web
|
||||
# Interfaccia web (5.1): linee guida
|
||||
|
||||
Aggiornato: 2026-09-23 (5.0, ADR-0007). L'interfaccia è servita dal bot stesso (`src/Encelado.Server/Web/wwwroot/`: `index.html`, `login.html`, `app.css`, `app.js`, `icon.svg`, `manifest.webmanifest`, incorporati nell'assembly). Nessuna libreria, nessun font remoto, nessun `<script src=http…>`: un test lo verifica (`EmbeddedUiTests`).
|
||||
Aggiornato: 2026-10-01 (5.1, ADR-0013). Sostituisce le linee guida Material 3 della 5.0. L'interfaccia della 5.1 riprende il linguaggio
|
||||
visivo e gli schemi di codice di Mimante (`C:\Sviluppo\Mimante\Mimante`, BidooBidBot): pagine compatte e dense, colore
|
||||
che ha un significato, dettagli nei tooltip, nessuna notifica laterale. È servita dal bot stesso
|
||||
(`src/Encelado.Server/Web/wwwroot/`, incorporata nell'assembly). Il contratto dei dati è in `docs/API.md`: i nomi dei
|
||||
campi valgono lì.
|
||||
|
||||
## Principi
|
||||
## 1. Principi
|
||||
|
||||
1. **La UI non decide niente.** Legge lo snapshot (`/api/snapshot`, `/api/stream`) e manda comandi (`POST /api/commands/<nome>`). Ogni regola di rischio sta nel motore.
|
||||
2. **Le stesse informazioni della dashboard di sempre**: equity, P&L di oggi, P&L aperto (conto e basket), drawdown, basket aperti con in attesa / orfane / esterne, margine; la tabella dei basket; prossimo evento, collegamento eToro, Telegram; l'attività. I dettagli stanno nei tooltip (`title`) e nel log, non in più riquadri.
|
||||
3. **Ogni numero ha un tooltip** con la formula o la fonte; ogni importo convertito porta nel tooltip il valore in USD e il tasso usato. Il ledger resta in USD.
|
||||
4. **Gli orari a schermo sono nel fuso scelto** (`ui.timeZone`, `TZ`); la barra in alto mostra sempre anche l'UTC, che è l'ora del ledger.
|
||||
5. **Le azioni irreversibili chiedono conferma** in un dialogo: chiusura di un basket, kill-switch (con la spunta «chiudi anche le esterne», deselezionata), reset (motivazione ≥ 10 caratteri), rimozione delle chiavi, ripristino della configurazione, avvio Live (frase `CONFERMO LIVE` scritta per intero).
|
||||
1. **La UI non decide niente.** Legge il tick (`/api/stream`) e le sezioni a richiesta, manda comandi con
|
||||
`POST /api/commands/<nome>` e impostazioni con `POST /api/settings`. Ogni regola di rischio sta nel motore.
|
||||
2. **Il colore viene solo dai token** (`css/tokens.css`) e ha un significato:
|
||||
- neutro = secondario;
|
||||
- accento = primario;
|
||||
- verde, ambra e rosso = ok, attenzione, pericolo;
|
||||
- oro = notevole (il migliore nel contesto, solo fra i bracci provati almeno una volta; il modello campione).
|
||||
|
||||
## Material 3 senza libreria
|
||||
Fanno eccezione, per forza di cose, i colori propri delle bandiere e il bianco della levetta.
|
||||
3. **Densità compatta.** Testo base a 13 px con cifre tabulari (`font-variant-numeric: tabular-nums`). Controlli alti
|
||||
30 px, righe di tabella 32 px (28 nelle tabelle compatte), barra in alto 46 px.
|
||||
4. **Layout fluido.** Niente `max-width` sui contenitori delle pagine. Si usano griglie con `minmax(0,1fr)` e colonne
|
||||
che si adattano alla larghezza; la pagina non scorre mai di lato, sono le tabelle a scorrere dentro il loro
|
||||
pannello. A 1920 e a 2560 px non resta nessuna fascia vuota a destra.
|
||||
5. **Il DOM si costruisce una volta sola e poi si aggiorna sul posto.** Le righe hanno una chiave e si riscrive solo la
|
||||
cella il cui valore è cambiato. Nessun `innerHTML` con dati.
|
||||
6. **Ogni numero ha un `title`** con il significato, la formula o la fonte. Gli importi riportano nel tooltip il
|
||||
valore in USD e il tasso usato.
|
||||
7. **Niente toast.** Una conferma di routine si vede come cambio di stato sul posto (colore del bottone, riga, esito
|
||||
accanto al campo). Una finestra al centro compare solo per errori, conferme e risultati importanti. Un comando
|
||||
rifiutato (`{ ok: false }`, anche i 400 della modalità `--sample`) apre la finestra con il messaggio del server.
|
||||
8. **I bottoni delle barre strumenti sono icone** con `title` e `aria-label`. Le azioni principali di una pagina sono
|
||||
bottoni con testo: Salva, Esegui ciclo, Bonifica orfane.
|
||||
9. **Le azioni irreversibili chiedono conferma**: chiusura di un basket, kill-switch, ripristino (motivazione di almeno
|
||||
10 caratteri), rimozione di chiavi e token, valori di fabbrica, avvio Live e ogni modifica che riavvia il motore in
|
||||
Live (frase `CONFERMO LIVE` scritta per intero). Nelle conferme distruttive il fuoco parte su «Annulla»: un Invio
|
||||
tenuto premuto non esegue niente. Nel kill-switch la casella «chiudi anche le esterne» parte come l'impostazione
|
||||
«Il kill-switch chiude anche le posizioni esterne» (`tick.closeForeignOnKill`, con una riga che lo dice quando è
|
||||
accesa) e la scelta fatta nel dialogo è quella che vale: va sempre al server come `foreign` esplicito.
|
||||
10. **Testi italiani, brevi.** «Non mettere scritte inutili che occupano solo spazio»: i dettagli vanno nel tooltip,
|
||||
nel log o nella pagina di dettaglio.
|
||||
|
||||
### Colori (token CSS in `:root`)
|
||||
## 2. Token
|
||||
|
||||
| Ruolo | Scuro (default) | Chiaro | Uso |
|
||||
Tema scuro predefinito, chiaro con gli stessi nomi (`:root[data-theme="light"]`). Senza un tema scelto, la pagina segue
|
||||
`prefers-color-scheme`: è il caso della pagina di accesso. Il tema si sceglie con ◐ nella barra o in Impostazioni ▸
|
||||
Interfaccia (`ui.theme`), ed è ricordato anche nel browser (`localStorage`, `js/boot.js` lo applica prima del primo
|
||||
disegno).
|
||||
|
||||
| Token | Scuro | Chiaro | Uso |
|
||||
|---|---|---|---|
|
||||
| `--primary` / `--on-primary` | `#adc6ff` / `#002e69` | `#005ac1` / `#ffffff` | pulsante AVVIA, tab attiva, focus, curva dell'equity |
|
||||
| `--primary-container` / `--on-primary-container` | `#1f4e9c` / `#d8e2ff` | `#d8e2ff` / `#001a41` | voce attiva del rail |
|
||||
| `--surface`, `--surface-container-low/-/high/highest` | `#101418`, `#181c20`, `#1c2024`, `#262a2f`, `#31353a` | `#f8f9ff`, `#f2f3f9`, `#eceef4`, `#e6e8ee`, `#e0e2e8` | sfondo, rail, card, KPI, intestazioni delle tabelle |
|
||||
| `--on-surface` / `--on-surface-variant` | `#e0e2e8` / `#c3c6d0` | `#191c20` / `#43474e` | testo, testo secondario |
|
||||
| `--outline` / `--outline-variant` | `#8d9099` / `#43474e` | `#74777f` / `#c3c6d0` | bordi di input e tabelle |
|
||||
| `--error` / `--error-container` | `#ffb4ab` / `#93000a` | `#ba1a1a` / `#ffdad6` | kill-switch, banner rosso, stato `Halted` |
|
||||
| `--up` / `--down` / `--warn` | `#7fd39a` / `#ff8a80` / `#f5b74f` | `#1b7f3b` / `#c62828` / `#9a6400` | **solo** P&L, pip, stati (verde/rosso), avvisi (giallo) |
|
||||
| `--bg` | #151920 | #eef1f5 | fondo della pagina |
|
||||
| `--surface` / `-2` / `-3` | #1c2129 / #232a34 / #2a323d | #fff / #f4f6f9 / #e9edf3 | pannelli, controlli, selezione |
|
||||
| `--line` | #2c3441 | #d7dde6 | bordi e separatori |
|
||||
| `--text` / `--muted` / `--faint` | #e6eaf1 / #93a0b4 / #5f6b7d | #1b2230 / #5b6778 / #9aa5b5 | testo, etichette, dati spenti |
|
||||
| `--accent` | #5b9cff | #2f6fe4 | primario, selezione, livello INFO |
|
||||
| `--ok` / `--warn` / `--bad` | #3ecf8e / #f2b640 / #f15b50 | #1f9d63 / #c98a10 / #d63b31 | utile, attenzione, perdita o pericolo |
|
||||
| `--gold` | #e5b94e | #b8891a | il migliore, il campione |
|
||||
| `--*-soft` | stessi colori al 12-18 % | | fondo di tag, pill, fasce |
|
||||
|
||||
Una sola tinta d'accento; contrasto ≥ 4,5:1 per il testo. Il tema si sceglie in Impostazioni ▸ Interfaccia (`ui.theme`: `dark` | `light`) e viene ricordato nel browser (`localStorage`, solo comodità per chi guarda); `prefers-color-scheme` è rispettato quando il file dice `dark` ma il sistema è chiaro solo per `color-scheme`.
|
||||
Altre variabili:
|
||||
|
||||
### Tipografia
|
||||
- `--ctl-h: 30px`, `--topbar-h: 46px`, `--nav-w: 212px`, `--nav-w-narrow: 56px`;
|
||||
- `--r: 6px` e `--r-lg: 8px` (finestre);
|
||||
- `--fs: 13px`, `--fs-small: 12px`, `--fs-tiny: 11px`, `--gap: 14px`.
|
||||
|
||||
`Roboto, "Segoe UI", system-ui, sans-serif`; monospazio `Cascadia Mono, JetBrains Mono, Consolas` per log, id e attività. Scala: titolo di pagina 20 px (title-large), titoli delle card 16 px (title-medium), KPI 24 px (headline-small), corpo 14 px, etichette 12 px. **Cifre tabulari** (`font-variant-numeric: tabular-nums`) su ogni numero.
|
||||
Scala dei testi:
|
||||
|
||||
### Forma, elevazione, stati
|
||||
- titolo della pagina 15 px/600;
|
||||
- titolo di sezione 13,5 px/600;
|
||||
- valore delle tessere tra 15 e 20 px (con `clamp` nella dashboard);
|
||||
- testo secondario 12 px, etichette minime 11 px.
|
||||
|
||||
Angoli 12 px (card, banner), 16 px (dialoghi grandi 28 px come da M3), pulsanti a pillola (999 px). Elevazione tonale (superfici a livelli), niente ombre salvo dialoghi e snackbar. State layer su hover (8 %) e pressed (12 %) tramite `::after`. `:focus-visible` con anello di 2 px in `--primary`.
|
||||
Pesi usati: 400 e 600 (700 solo per KILL e i tag di livello).
|
||||
|
||||
### Componenti
|
||||
## 3. File
|
||||
|
||||
| Componente | Dove | Note |
|
||||
|---|---|---|
|
||||
| Navigation rail | sinistra, 80 px chiuso / 256 px aperto | quattro voci: Dashboard, Storico ordini, Log, Impostazioni; stato ricordato (`ui.navExpanded` e `localStorage`); sotto 600 px diventa un drawer con scrim; in fondo i chip ambiente e stato |
|
||||
| Top app bar | sopra la pagina | titolo della pagina, ora UTC e ora nel fuso, selettore della valuta, AVVIA/FERMA, KILL-SWITCH (attivo solo a motore acceso); linear progress durante un comando |
|
||||
| Cards | dashboard, contesto, impostazioni | KPI con etichetta, valore, riga secondaria |
|
||||
| Data table compatta | basket, storico, log | intestazione fissa, righe da 32 px, allineamento a destra dei numeri; sotto 600 px la tabella dei basket diventa cards |
|
||||
| Chips | ambiente (`PAPER` blu, `DEMO` giallo, `LIVE` rosso), stato del motore, stato del basket, origine della posizione | testo in minuscolo per gli stati |
|
||||
| Buttons | filled (AVVIA, Salva, conferme), tonal (Applica, Avvia il ripristino), outlined danger (KILL-SWITCH), text (Chiudi, Esporta) | mai due filled affiancati |
|
||||
| Select, input, switch | filtri, impostazioni, Segui nel log | validazione lato server con messaggio accanto al campo |
|
||||
| Dialog | conferma, prompt (motivazione, `CONFERMO LIVE`), ripristino in cinque passi | `<dialog>` nativo, `showModal`, Esc chiude |
|
||||
| Snackbar | esito dei comandi | 4 s, 8 s se errore |
|
||||
| Banner | dashboard | rosso per errore, kill-switch con residuo, equity stop, sospensione; giallo per entrate bloccate, non riconciliate, orfane |
|
||||
| Tooltip | `title` su ogni numero e riga | la formula, la fonte, il valore in USD |
|
||||
|
||||
### Classi di finestra
|
||||
|
||||
| Classe | Larghezza | Layout |
|
||||
|---|---|---|
|
||||
| compact | < 600 px | rail nascosto (menu ☰), KPI su due colonne, basket a cards, orologi nascosti |
|
||||
| medium | 600-839 px | rail 80 px, KPI su due colonne, contesto su una colonna, impostazioni su una colonna |
|
||||
| expanded | ≥ 840 px | rail 80/256 px, KPI su tre colonne (due righe), contesto su tre, impostazioni su due |
|
||||
|
||||
### Accessibilità
|
||||
|
||||
Tastiera completa (Tab su rail, pulsanti, tabelle, dialoghi; Esc chiude drawer e dialoghi), `aria-label` su icone e selettori, `aria-current="page"` sulla voce attiva, `role="tablist"/"tab"/"tabpanel"` nello storico, `role="status"` su banner e snackbar, link «Vai al contenuto», `prefers-reduced-motion` (nessuna transizione), `prefers-color-scheme`.
|
||||
|
||||
## Pagine
|
||||
|
||||
- **Dashboard**: banner, sei KPI, tabella dei basket (nome e cross, stato, z, ρ, HL, pip, TP, P&L, costo, prossimo evento, Chiudi), preset, tre card di contesto, attività (ultime righe di log).
|
||||
- **Storico ordini**: tre tab. *Ordini* (da `orders.jsonl`: unità richieste ed eseguite, prezzi, slippage, stato, esito, id), *Posizioni* (storico eToro classificato `basket` / `orfana-bot` / `esterna` / `movimento di cassa`, con P&L lordo, fee, netto, pip, durata, motivo), *Profitti per periodo* (oggi, ieri, 7 e 30 giorni, mese corrente e precedente, anno, tutto, intervallo personalizzato; curva dell'equity realizzata in SVG). Filtri e **Esporta CSV** (`;`, colonna `motivazione`).
|
||||
- **Log**: livello, ricerca, «Segui», 2000 righe per pagina lette a incrementi (`/api/log?after=`).
|
||||
- **Impostazioni**: configurazione a gruppi (eToro, esecuzione, notifiche, interfaccia/valuta, log) con validazione; chiavi eToro (verifica e salvataggio cifrato); ripristino in cinque passi e ripristino dei valori predefiniti; **Ricerca** (stato del modello in ombra, bandit, volatilità, criterio di riattivazione, «Esegui ciclo di apprendimento»); **Diagnostica** (strategia e run, percorsi, .NET, sistema, uptime, quote API, fuso, bonifica); **Informazioni** (nome, autore, versione, data di build, commit, licenza, documentazione).
|
||||
- **Login**: solo con `ENCELADO_WEB_TOKEN`; cookie HttpOnly per 30 giorni.
|
||||
|
||||
## Flusso dei dati
|
||||
|
||||
`/api/stream` (SSE, `event: snapshot`, uno al secondo) → `apply(snapshot)` → `render()`; se il browser non ha `EventSource`, polling di `/api/snapshot` ogni 2 s; `?once=1` scatta una sola lettura (per gli screenshot). I comandi rispondono `{ok, message, …}` e finiscono nella snackbar; l'esito vero arriva con lo snapshot successivo. Il log legge `/api/log` ogni 1,5 s solo mentre la pagina Log è aperta.
|
||||
|
||||
## Screenshot
|
||||
|
||||
`docs/img/` (dashboard, storico, log, impostazioni, mobile), presi dal server in modalità campione con `scripts\screenshots.ps1` (o `sh scripts/screenshots.sh`): avvia il server con `--sample` su una porta libera, apre ogni pagina con Edge headless (`?once=1`, 1440×900 e 420×860) e lo ferma. A mano, una pagina:
|
||||
|
||||
```powershell
|
||||
dotnet run --project src/Encelado.Server -- --sample --port 8085
|
||||
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --headless=new --disable-gpu --hide-scrollbars --window-size=1440,900 --virtual-time-budget=5000 --user-data-dir=$env:TEMP\edge-shot --screenshot=docs\img\dashboard.png "http://127.0.0.1:8085/?once=1#/dashboard"
|
||||
```
|
||||
wwwroot/index.html solo lo scheletro (XHTML ben formato: ogni elemento chiuso, attributi con valore)
|
||||
wwwroot/login.html scheda di accesso, senza JavaScript (/js/* chiede la sessione): il server sostituisce
|
||||
<!--login-error--> con <p class="login-error" role="alert">…</p>
|
||||
wwwroot/css/tokens.css i token css/app.css i componenti css/pages/<pagina>.css le regole di una pagina
|
||||
wwwroot/js/boot.js script classico nel <head>: applica il tema salvato prima del primo disegno
|
||||
wwwroot/js/app.js ingresso (modulo): barra in alto, menu, striscia degli allarmi, router, tema
|
||||
wwwroot/js/state.js store del tick, pub/sub, disegno in requestAnimationFrame, sezioni su richiesta, comandi
|
||||
wwwroot/js/stream.js EventSource su /api/stream (chiuso dopo 15 s di scheda nascosta), ?once=1 per gli screenshot
|
||||
wwwroot/js/util.js el() e scritture condizionate, formati italiani con Intl in cache, importi, api(), memoria del browser
|
||||
wwwroot/js/grid.js tabella a righe con chiave e aggiornamento per cella
|
||||
wwwroot/js/ui.js sezioni, tessere, liste chiave/valore, colonne affiancate, Markdown sicuro, SVG sanificato
|
||||
wwwroot/js/charts.js gauge dello z, barre, barre centrate sullo zero, sparkline, calibrazione, pesi
|
||||
wwwroot/js/dialog.js finestra centrale: conferma, richiesta di testo (CONFERMO LIVE), messaggi
|
||||
wwwroot/js/actions.js AVVIA, FERMA, KILL, chiudi basket, residui, ripristino, pausa, bonifica, ciclo di apprendimento, esci
|
||||
wwwroot/js/baskets.js come si legge un basket (stato, verso, p_ML, prossimo evento nel fuso del browser)
|
||||
wwwroot/js/labels.js le parole del ledger e del motore in italiano (evento, codici di motivo, motivi d'uscita,
|
||||
stati degli ordini, sorgenti del log); il codice resta nel tooltip
|
||||
wwwroot/js/icons.js flags.js clocks.js split.js
|
||||
wwwroot/js/pages/<pagina>.js una pagina = { mount(section, ctx, params), unmount(), render(tick), params(p)? }
|
||||
```
|
||||
|
||||
Prima di dichiarare finita una modifica: `EmbeddedUiTests` e `WebHostTests` verdi, screenshot rifatti se cambia una pagina, revisione visiva con l'utente.
|
||||
Ogni file sotto `wwwroot/` è servito al suo percorso (`/css/app.css`, `/js/pages/log.js`), con il tipo dal suffisso
|
||||
(`.js` come `text/javascript`, altrimenti il browser rifiuta i moduli), `ETag` e 304. Libere senza sessione solo
|
||||
`/login`, `/logout`, `/css/*`, `/img/*`, `/icon.svg`, `/manifest.webmanifest` e `/api/health`.
|
||||
|
||||
Le pagine sono moduli ES importati staticamente da `app.js` (niente `import()`). Esiste nel DOM solo la pagina visibile.
|
||||
|
||||
## 4. Struttura
|
||||
|
||||
### Barra in alto (46 px, tutta la larghezza)
|
||||
|
||||
Da sinistra a destra:
|
||||
|
||||
1. Menu (solo sotto 480 px).
|
||||
2. Logo e «Encelado».
|
||||
3. **Pill del motore**: il pallino dice lo stato, il testo il conto. Sostituisce le scritte «demo» e «in esecuzione»
|
||||
che nella 5.0 stavano in fondo al menu.
|
||||
- Pallino verde: in esecuzione. Grigio: fermo. Ambra: in avvio o in arresto, pausa, entrate bloccate, recupero,
|
||||
perdita giornaliera, heartbeat in ritardo sul suo intervallo (`tick.heartbeatSeconds`). Rosso: errore o bloccato.
|
||||
- Testo `DEMO` con bordo accento, oppure `LIVE` su fondo rosso.
|
||||
- Il tooltip dà lo stato completo; il clic apre Sistema.
|
||||
4. **Pill eToro**: pallino secondo `health.api` e latenza. Il tooltip dà scarto dell'orologio e quota più usata.
|
||||
5. **Pill dei numeri**: Equity, Oggi (con «stima» quando è provvisorio), Aperto, DD, Basket aperti/massimo. Ognuna ha il
|
||||
tooltip con formula, USD e tasso.
|
||||
6. **Orologi** (vedi sotto).
|
||||
7. A destra:
|
||||
- la pill dell'allarme più grave (icona e parola; sotto 560 px solo l'icona), cliccabile;
|
||||
- **KILL** (rosso, attivo solo con il motore in esecuzione);
|
||||
- tema ◐;
|
||||
- **accensione** ⏻: verde quando il motore gira (clic = FERMA con conferma), neutra quando è fermo (clic = AVVIA; in
|
||||
Live chiede la frase), disattivata durante avvio e arresto.
|
||||
|
||||
Le pill cedono lo spazio per priorità: prima Basket (<1600 px), poi DD (<1500), Aperto (<1380), eToro (<1240),
|
||||
orologi (<1024), Equity (<720) e Oggi (<560). Motore, accensione, KILL e allarme restano sempre. La barra non va mai su
|
||||
due righe: quello che non ci sta scivola su una seconda riga invisibile. Non c'è il selettore della valuta, che sta in
|
||||
Impostazioni ▸ Interfaccia.
|
||||
|
||||
### Orologi
|
||||
|
||||
Un orologio per ogni fuso delle valute trattate, da est a ovest:
|
||||
|
||||
- Nuova Zelanda (`Pacific/Auckland`, NZD);
|
||||
- Australia (`Australia/Sydney`, AUD);
|
||||
- Europa centrale e Svizzera (`Europe/Zurich`, EUR+CHF);
|
||||
- Stati Uniti e Canada (`America/New_York`, USD+CAD).
|
||||
|
||||
Solo `HH:mm`, aggiornati allo scoccare del minuto e fermi con la scheda nascosta. Le bandiere sono SVG in linea, perché
|
||||
Windows non disegna le emoji delle bandiere.
|
||||
|
||||
- **Il fuso del computer** compare come quinto orologio, con l'icona della casa, solo se la sua firma dell'ora legale
|
||||
(scarti a metà gennaio, aprile, luglio, ottobre e adesso) è diversa da tutte e quattro. Altrimenti un pallino
|
||||
accento segna l'orologio corrispondente: da Europe/Rome si vede EU+CH.
|
||||
- **Fuori dalla sessione** locale (08-17 nei giorni feriali, festivi esclusi) l'orologio è spento.
|
||||
- **Il tooltip** dice città, ora con sigla e scarto UTC, ora UTC, sessione, valute ed eventuale «un giorno avanti o
|
||||
indietro». In barra compare anche «+1» o «−1».
|
||||
|
||||
### Menu a sinistra (212 px, 56 px compresso)
|
||||
|
||||
Le voci sono Dashboard, Basket, Posizioni, Mercato, Storico, Apprendimento, Log, Sistema e Impostazioni, con icona.
|
||||
|
||||
- **Contatori.** Posizioni in rosso quando ci sono gambe orfane. Log con gli errori arrivati dall'ultima visita alla
|
||||
pagina (contati da quando il browser ha aperto l'interfaccia).
|
||||
- **In fondo** c'è solo «Comprimi il menu». La scelta è salvata in `ui.navExpanded` e nel browser.
|
||||
- **Finestre strette.** Sotto 700 px il menu mostra solo le icone. Sotto 480 px sparisce dietro il bottone del menu e
|
||||
si apre sopra la pagina.
|
||||
|
||||
### Striscia degli allarmi
|
||||
|
||||
Una riga sotto la barra, solo quando c'è un allarme da spiegare. Gli allarmi, in ordine di gravità:
|
||||
|
||||
| Allarme | Colore | Azione |
|
||||
|---|---|---|
|
||||
| motore in errore | rosso | Sistema |
|
||||
| kill-switch con residuo | rosso | Chiudi residui |
|
||||
| bloccato (kill o equity stop) | rosso | Sblocca…, cioè la procedura di ripristino |
|
||||
| Live da confermare | rosso | Avvia… |
|
||||
| segreti bloccati | rosso | Apri impostazioni |
|
||||
| nessuna chiave salvata (`health.secrets = empty`, motore fermo) | ambra | Apri impostazioni |
|
||||
| non riconciliato | ambra | Posizioni |
|
||||
| perdita giornaliera (fino alle 00:00 UTC anche se l'equity recupera: `dailyLossLatched`) | ambra | |
|
||||
| entrate bloccate | ambra | |
|
||||
| pausa | ambra | Riprendi |
|
||||
| recupero | ambra | |
|
||||
| gambe orfane | ambra | Posizioni |
|
||||
| variabili d'ambiente ignorate | tenue | Dettagli (Sistema) |
|
||||
|
||||
Si vede il primo; gli altri sono in «+N altri», con l'elenco nel tooltip. Se il tick non arriva per più di 4,5 s compare
|
||||
«Connessione con il bot interrotta: riprovo…».
|
||||
|
||||
### Pagine
|
||||
|
||||
Ogni pagina ha:
|
||||
|
||||
1. una **barra strumenti** su una sola riga allineata: titolo 15 px, azioni, filtri, contatori a destra. Tutti i
|
||||
controlli sono alti 30 px e centrati; le etichette stanno a sinistra del controllo o come segnaposto, mai sopra.
|
||||
Un testo lungo (il percorso del file di log) si accorcia con i puntini invece di mandare a capo i controlli;
|
||||
2. un **corpo** che scorre dentro la pagina, con margini e spazi di 14 px.
|
||||
|
||||
## 5. Componenti
|
||||
|
||||
- **Bottoni**:
|
||||
- `.btn`, alto 30 px, nelle varianti `primary`, `danger`, `ghost`, `sm` (26 px);
|
||||
- `.icon-btn`, 30×30 con icona 16 px, nelle varianti di colore `c-ok`, `c-bad`, `c-acc`;
|
||||
- azioni di riga: bottoni 26×26 in un `div.acts` dentro la cella. La cella resta una cella di tabella: una `td` con
|
||||
`display:flex` perderebbe la larghezza fissa della colonna e le azioni scivolerebbero all'estremo destro;
|
||||
- `.kill` per il kill-switch.
|
||||
- **Campi**: `input.txt`, `select.txt` (30 px). I numeri sono allineati a destra. L'unità corta (fino a 13 caratteri:
|
||||
«secondi», «% dell'equity») sta dentro il campo; una lunga («MB (0 = nessuna rotazione)», «ora UTC (−1 = spento)»)
|
||||
sta accanto all'etichetta, dove non copre mai il valore. Un numero con `allowEmpty` lasciato vuoto vale «dal preset».
|
||||
- **Interruttori**: `.switch` (34×18). Nelle barre strumenti si usa `.chk`: una levetta con il testo, nella stessa
|
||||
scatola da 30 px degli altri controlli («Segui» del Log).
|
||||
- **Segmentato**: `.seg`, per le viste dello Storico.
|
||||
- **Schede**: `.tabs`, per il pannello del Basket.
|
||||
- **Stati**:
|
||||
- `.chip` (26 px) con `.dot` e icona (14 px) nella barra in alto;
|
||||
- `.tag` per lo stato di una riga (Aperto verde, Attesa ambra, Inattivo tenue, Errore rosso). Vale la parola del
|
||||
server: un basket spento in Attesa B, in Errore o in Uscita lo dice, e la riga è attenuata solo se è spento e
|
||||
senza niente sul conto;
|
||||
- `.pill`;
|
||||
- `.lvl` per il livello del log: INFO accento, WARN ambra, ERROR rosso, DEBUG e TRACE tenui.
|
||||
- **Sezioni**: `.section`, con `h2` alto 38 px (icona, titolo, sottotitolo, strumenti a destra) e corpo `.in` oppure
|
||||
`.tw` (tabella che scorre).
|
||||
- **Colonne affiancate**: `stacks()` in `ui.js` dispone le sezioni in colonne («masonry»). Il numero di colonne
|
||||
dipende dalla larghezza. Le sezioni si ridistribuiscono solo quando cambia il numero di colonne o dopo il primo
|
||||
caricamento, mai mentre cambiano i dati: niente salta sotto gli occhi.
|
||||
- **Tessere**: `tile()`, con etichetta, valore e una o due righe di sotto testo (ognuna con i puntini se troppo lunga),
|
||||
barra facoltativa. La spiegazione completa sta nel `title`.
|
||||
- **Chiave/valore**: `kv()`, a colonne automatiche (`kv2`) o su una colonna (`kv`), aggiornabile per chiave.
|
||||
- **Tabelle**: `Grid` in `grid.js`.
|
||||
- Righe con chiave. Le colonne danno `text`, `tip` e `klass`, oppure `render` + `sig` quando la cella contiene
|
||||
elementi: gauge, barre, bandiere.
|
||||
- Layout fisso con larghezze dalle intestazioni; i testi lunghi finiscono con i puntini e il testo intero nel
|
||||
`title`. Una sola colonna senza larghezza prende lo spazio che resta.
|
||||
- `hideBelow` nasconde una colonna sotto una larghezza del contenitore: la colonna resta con larghezza zero, perché
|
||||
`display:none` lascerebbe una colonna fantasma.
|
||||
- `narrow` le dà una larghezza minore sotto una o più soglie.
|
||||
- Oltre `virtualizeOver` righe (Storico) si disegnano solo le righe visibili.
|
||||
- L'ordinamento con clic sull'intestazione è ricordato nel browser.
|
||||
- **Grafici** (niente librerie):
|
||||
- gauge dello z: fascia d'ingresso ambra da z_in a z_stop, tacche rosse allo stop, segno blu, ambra o rosso;
|
||||
- pip/TP con barra;
|
||||
- barre centrate sullo zero (sentiment, pesi, contributi);
|
||||
- sparkline dell'AUC con tratteggio a 0,5;
|
||||
- curva di calibrazione (10 fasce, diagonale = perfetta);
|
||||
- z del basket nelle ultime 20 chiusure di barra, con le soglie;
|
||||
- curva del realizzato dallo `equitySvg` del server, letto come XML e sanificato.
|
||||
- **Pannello a destra**: `split.js`, maniglia trascinabile che cambia solo `--panel-w`. Doppio clic ripristina la
|
||||
larghezza. Sotto 900 px il pannello va sotto l'elenco.
|
||||
- **Finestre**: `modal()`, `confirmDialog()` (con casella facoltativa e una riga di spiegazione), `promptDialog()` (con
|
||||
validazione: il bottone si abilita solo con il testo giusto), `notice()`. Esc o il clic fuori chiudono; il fuoco resta
|
||||
nella finestra e parte dal campo di testo, altrimenti dall'ultimo bottone, ma su «Annulla» quando l'azione è
|
||||
distruttiva.
|
||||
- **Bandiere**: `flags.js`, sprite SVG iniettato una volta, 18×12 (CH 12×12). Ci sono EU, CH, US, CA, AU, NZ, GB e
|
||||
JP; il testo è nel tooltip dell'elemento che le contiene.
|
||||
|
||||
## 6. Le pagine
|
||||
|
||||
| Pagina | Dati | Contenuto |
|
||||
|---|---|---|
|
||||
| **Dashboard** | tick; `/api/market?calendarDays=7&impact=High,Medium&news=0` | 9 tessere: equity, P&L oggi (con «stima»; è il periodo «oggi» dello Storico), aperto, drawdown con barra verso lo stop, perdita giornaliera con barra (quando scatta resta bloccata fino alle 00:00 UTC anche se l'equity recupera: `dailyLossLatched`, ora di sblocco nel fuso del browser), margine, basket con il preset, chiusi oggi, apprendimento con barra. Tabella dei 5 basket: bandiere e nome con il cross, stato, verso, z con gauge, ρ, HL, pip/TP, P&L, costo, p_ML, prossimo evento (ora nel fuso del browser e conto alla rovescia: l'etichetta del motore porta l'ora UTC), chiudi; un clic apre il Basket. Prossimi eventi, mercato (8 quotazioni con lo spread colorato rispetto alla mediana; «—» per uno strumento non ancora quotato), registro (le ultime `tick.statusLines` righe, cioè Impostazioni ▸ Log ▸ righe di attività, 60 prima del primo tick; clic = Log). A 1440×900 sta tutto senza scorrere; da 1500 px di pagina eventi e mercato vanno in una colonna a destra. |
|
||||
| **Basket** | tick; `/api/baskets/detail?name=` ogni 2 s; `/api/learning` per la scheda ML | Elenco con tutte le colonne (stato, intento, z, z_in, z_stop, ρ_W, ρ_20, HL, pip/TP, P&L, costo, spread×, p_ML, barre, aggiunte, z d'ingresso, evento) e sotto il grafico dello z del basket scelto. Pannello con schede: Stato (intento, ultima decisione con i motivi, soglie contro valori con ✓/✗, cost gate, dimensione con il vincolo), Posizione (dati del basket e gambe, oppure la gamba in attesa), Segnale, Contesto, ML (p_ML, contributi del modello che l'ha data, feature: «Feature all'ingresso» mentre il basket è in posizione o in attesa di una gamba, «Feature all'ultima barra» altrimenti; una p_ML senza spiegazione conservata dice «Nessun contributo che spieghi questa p_ML…» invece di mostrare contributi di un altro modello), Decisioni (ultime 20). Eventi del ledger, codici e vincoli in italiano (`labels.js`), il codice nel tooltip. |
|
||||
| **Posizioni** | `/api/positions` | Tessere per origine: tutte, basket, orfane del bot, esterne. Ogni posizione del conto: origine, basket e gamba, strumento, verso, unità, apertura, attuale, pip, P&L, margine, leva, SL/TP, aperta da; bonifica delle orfane. Ordini in attesa con la loro età. |
|
||||
| **Mercato** | `/api/market?calendarDays=7&impact=High,Medium,Low,Holiday&news=50`; tick | Quotazioni (spread, mediana, rapporto, età, ATR, usato da): gli strumenti dei basket prendono bid, ask, spread ed età dal tick ogni secondo, l'età delle coppie di sola conversione cresce con l'orologio (la sezione è ricostruita al più ogni 15 s); calendario con filtri per impatto e valuta (ricordati nel browser; una valuta ricordata ha sempre il suo chip, anche in una settimana senza eventi), conto alla rovescia e blackout; sentiment 1 h, 4 h, 24 h per valuta con risk-off; notizie con i link; valute di visualizzazione; volatilità per basket. |
|
||||
| **Storico** | `/api/history/orders`, `positions`, `periods`; tick | Tre viste (Ordini, Posizioni, Profitti per periodo con la curva del realizzato), filtri nella barra, esportazione CSV dal server. `#/storico?vista=periodi` apre direttamente una vista. I filtri basket e strumento vengono dai basket del tick (anche a motore fermo) e si ricostruiscono quando arriva il primo tick; un filtro ricordato che l'elenco non conosce resta fra le opzioni, visibile e annullabile. Motivi d'uscita e stati degli ordini in italiano, il codice nel tooltip. |
|
||||
| **Apprendimento** | `/api/learning` | Stato e motivo; «Esegui ciclo» (spento mentre gira, con la fase in corso); esportazione JSON. 10 tessere: etichettati/300, win rate, P&L netto, AUC mobile con intervallo, Brier, modello, bandit, volatilità, ultimo e prossimo ciclo. Avvisi. Poi le sezioni: attivazione (criteri ✓/✗), cosa ha imparato (pesi ordinati, 15 + «mostra tutti»), per basket, bandit 3×3 con il migliore in oro (solo un braccio provato almeno una volta: un bandit nuovo non ne ha), ultimo ciclo (logistica contro MLP, calibrazione, AUC nel tempo), stato dei modelli, dataset per basket, preset e uscita, calibrazione per fascia, proposte, registro dei modelli, file, osservazioni (Markdown reso in modo sicuro). |
|
||||
| **Log** | righe del tick; `/api/log` | Barra su una riga: livello, «Cerca…», «Segui», conteggio, nome del file (il percorso intero nel tooltip), esporta. Una riga per messaggio: ora nel fuso del browser, tag del livello colorato, origine in italiano (la classe nel tooltip), messaggio con i puntini e con i codici del ledger in italiano («motivo take-profit»). Il clic apre il testo intero; il tooltip, la ricerca (come il `q` del server) e l'esportazione usano il testo del file. Al massimo 2000 righe nel DOM. |
|
||||
| **Sistema** | `/api/system` ogni 3 s | Motore (con Pausa/Riprendi e Ripristino…; heartbeat giudicato sul suo intervallo, `heartbeatSeconds`, rosso oltre la soglia di `/api/health`), collegamento eToro con le quote, feed, Telegram (messaggio di prova), segreti (sblocco e ripartenza, variabili ignorate), processo, disco, log, interfaccia web (Esci), diagnostica (bonifica), informazioni. |
|
||||
| **Impostazioni** | `/api/settings` | Gruppi disposti in colonne, etichetta a sinistra e controllo a destra, levette per i sì/no, numeri a destra con l'unità, un'icona per l'effetto: ⚡ subito, ⚙ nel motore, ↻ riavvia il motore. Pannelli speciali: chiavi eToro demo e live (gruppo `conto`), token Telegram (`telegram`), Esci (`interfaccia`), segreti bloccati, valori predefiniti; il gruppo `avanzate` è chiuso. «Salva (n)» manda solo i campi diversi dal valore che il server ha adesso (riletto a ogni salvataggio: tornare a un valore di prima è una modifica); se serve la frase CONFERMO LIVE la chiede e ripete; l'esito di ogni campo compare accanto per qualche secondo. |
|
||||
| **Accesso** | `POST /login` | Logo, «Encelado», «Password interfaccia», «Entra»; errore «Password errata.». |
|
||||
|
||||
## 7. Flusso dei dati e prestazioni (regole non negoziabili)
|
||||
|
||||
- **Un solo store** (`state.js`), alimentato dal tick SSE. Una sola pagina visibile, che disegna in
|
||||
`requestAnimationFrame`: con la scheda nascosta non si disegna niente.
|
||||
- **L'EventSource si chiude dopo 15 s di scheda nascosta** e si riapre quando torna visibile (il server smette di
|
||||
calcolare i frame). Senza `EventSource` si legge `/api/snapshot` ogni 2 s. Un 401 porta a `/login`.
|
||||
- **Le sezioni pesanti** si leggono con `watch()` solo mentre la loro pagina è visibile: subito, quando cambia
|
||||
`tick.versions[chiave]` e ogni 30 s, con `If-None-Match` (304 gratuito). Il dettaglio del basket si legge ogni 2 s,
|
||||
Sistema ogni 3 s. Nessun altro polling sotto i 2 s.
|
||||
- **Le righe del log** arrivano nel tick come differenza e si aggiungono per `seq`. Su un salto o una riconnessione si
|
||||
recupera il mancante con `/api/log?after=`. Al primo tick si caricano le ultime 300 righe (o `statusLines`, se sono
|
||||
di più, fino a 2000).
|
||||
- **Ogni POST e DELETE** (`api()` in `util.js`, l'unica `fetch`) manda `Content-Type: application/json`, anche senza
|
||||
corpo: il server rifiuta gli altri con 415, così un modulo di un altro sito non può comandare il bot.
|
||||
- **Tabelle con chiave**: righe create una volta; `textContent`, `title` e `className` scritti solo se diversi. Mai
|
||||
`innerHTML` con dati: lo usano solo i percorsi statici delle icone. L'SVG del server passa da `DOMParser` in XML e da
|
||||
una lista di elementi ammessi.
|
||||
- **Formattatori `Intl` in cache**, uno per formato; nessun formattatore creato per valore.
|
||||
- **CSS**:
|
||||
- niente `backdrop-filter`, niente `color-mix`;
|
||||
- niente transizioni su proprietà di layout (solo la levetta);
|
||||
- `table-layout: fixed` con le larghezze delle colonne;
|
||||
- `content-visibility: auto` sulle righe del log;
|
||||
- `prefers-reduced-motion` spegne animazioni e transizioni.
|
||||
- **Importi**: arrivano in USD e il browser li converte con `fxRates[valuta].usdPerUnit`. Il tooltip mostra USD e
|
||||
tasso. Le pagine costruite dai dati delle sezioni ridisegnano gli importi quando cambia la valuta.
|
||||
- **Misure** con il server vero in `--sample`, flusso a 1 Hz, 1440×900, finestre di 10 s (protocollo DevTools,
|
||||
`Performance.getMetrics`): dashboard circa 64 ms di lavoro del thread principale ogni 10 s (0,6 %: 11 ms di script,
|
||||
9 di layout, 16 di stile), Basket 47 ms, Log 32 ms; heap tra 1,5 e 2,1 MB. Il tick pesa circa 6 KB al secondo per
|
||||
client (più le righe di log nuove).
|
||||
- **Peso**: circa 295 KB di JavaScript non minificato (circa 90 KB con gzip), 60 KB di CSS. Pesano i tooltip in
|
||||
italiano su ogni numero, le etichette del ledger e le nove pagine importate staticamente. Kestrel non comprime i
|
||||
file statici.
|
||||
|
||||
## 8. Adattamento alla larghezza
|
||||
|
||||
Provato a 420×860, 1024×768, 1440×900, 1920×1080 e 2560×1440 con il server vero (e a 800×1000 e 1280×720 con il mock di
|
||||
sviluppo).
|
||||
|
||||
- Le griglie delle tessere passano da 9 colonne a 5 e poi a 3.
|
||||
- Dashboard, Mercato, Apprendimento, Sistema e Impostazioni dispongono le sezioni su 1, 2 o 3 colonne.
|
||||
- Nelle tabelle le colonne meno importanti cedono il posto (`hideBelow`, `narrow`); se non basta la tabella scorre
|
||||
dentro il suo pannello, la pagina mai.
|
||||
- Il pannello del Basket va sotto l'elenco sotto 900 px.
|
||||
|
||||
## 9. Accessibilità e testi
|
||||
|
||||
- Tutto si raggiunge da tastiera; il fuoco è visibile (contorno accento di 2 px).
|
||||
- I bottoni a icona hanno `aria-label`. La striscia degli allarmi ha `role="status"`, le finestre `role="dialog"`.
|
||||
- Testi in italiano e brevi; i numeri con il formato italiano (1.234,56; −1,23 con il vero segno meno; «12,34 %»).
|
||||
- Gli orari a schermo sono nel fuso del browser; l'UTC compare solo nei tooltip e nei testi che il motore scrive per
|
||||
il ledger (motivazioni, intenti).
|
||||
|
||||
## 10. Verifica visiva (screenshot)
|
||||
|
||||
`docs/img/` contiene una foto per pagina a 1440×900 (`dashboard`, `dashboard-chiaro`, `basket`, `posizioni`,
|
||||
`mercato`, `storico`, `apprendimento`, `log`, `sistema`, `impostazioni`, `login`) e `mobile` (la dashboard a
|
||||
420×860). Si rifanno tutte con il server vero in modalità campione:
|
||||
|
||||
```powershell
|
||||
scripts\screenshots.ps1 [-Port 58085] [-Only dashboard,mobile]
|
||||
sh scripts/screenshots.sh [porta]
|
||||
```
|
||||
|
||||
Lo script compila, avvia `Encelado.Server --sample` su cartelle temporanee e senza password, fotografa e ferma tutto.
|
||||
|
||||
- `?once=1` legge un solo snapshot e non apre lo stream: con uno stream aperto un browser headless non considera mai
|
||||
finito il caricamento della pagina. `?theme=light|dark` forza il tema.
|
||||
- Le foto da computer usano `msedge --headless=new --window-size=… --screenshot=…`.
|
||||
- **Edge per desktop non stringe la finestra sotto circa 500 px**: `--window-size=420,860` darebbe una pagina larga
|
||||
500 tagliata a destra. La foto `mobile` passa quindi dal protocollo DevTools con l'emulazione della finestra
|
||||
(`Emulation.setDeviceMetricsOverride`): in PowerShell con `ClientWebSocket`, in `screenshots.sh` con
|
||||
`node scripts/cdp-shot.mjs` (Node 22+, nessun pacchetto; senza Node ripiega su `--window-size`).
|
||||
- A mano, una pagina:
|
||||
|
||||
```powershell
|
||||
dotnet run --project src/Encelado.Server -- --sample --port 8085
|
||||
& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --headless=new --disable-gpu --hide-scrollbars --window-size=1440,900 --virtual-time-budget=6000 --user-data-dir=$env:TEMP\edge-shot --screenshot=$PWD\shot.png "http://127.0.0.1:8085/?once=1#/dashboard"
|
||||
```
|
||||
|
||||
- Ogni foto va guardata: niente sbordature, niente fasce grigie, niente pannelli vuoti stirati, controlli allineati.
|
||||
- In `--sample` i comandi, i salvataggi delle impostazioni e le rotte dei segreti rispondono `{ ok: false }` (HTTP 400,
|
||||
«modalità dimostrativa»): la pagina mostra il messaggio nella finestra centrale e niente viene salvato. Impostazioni
|
||||
mostra i valori di fabbrica; il server campione lavora in cartelle temporanee e non tocca configurazione, segreti,
|
||||
dati o Telegram dell'operatore.
|
||||
|
||||
## 11. Per chi modifica l'interfaccia
|
||||
|
||||
1. Solo token per i colori; controlli da 30 px; niente `max-width`; niente librerie, CDN, font web, `@import` o
|
||||
`import()`.
|
||||
2. I dati diventano nodi di testo (`el()`), mai HTML. Un nuovo numero porta il suo `title`.
|
||||
3. Una nuova tabella usa `Grid` con righe a chiave e colonne con larghezza; una nuova sezione a richiesta usa `watch()`
|
||||
con la sua chiave di `versions`. Un campo nuovo del server si scrive prima in `docs/API.md`.
|
||||
4. `index.html` e `login.html` restano XML ben formato: elementi chiusi, `hidden="hidden"`, niente `xlink:`.
|
||||
5. Una parola del ledger o del motore (evento, codice di motivo, motivo d'uscita, stato di un ordine, sorgente del log)
|
||||
passa da `labels.js`: la parola in italiano sullo schermo, il codice nel tooltip. Un valore che il server può mandare
|
||||
`null` si mostra «—»: mai un conto fatto su `null` (`null × 1e4` è 0 e si stamperebbe «0,0»).
|
||||
6. Prima di chiudere:
|
||||
- `dotnet test`: `EmbeddedUiTests` controlla che le due pagine siano XHTML ben formato, che ogni file citato da
|
||||
`index.html` e ogni `import` statico dei moduli esista e esporti i nomi importati (un nome mancante blocca tutta
|
||||
l'app con un `SyntaxError`), che nessun file citi un altro host, che i token abbiano i due temi con gli stessi
|
||||
nomi, che l'app usi `/api/stream` e chieda `CONFERMO LIVE`, e che il login mandi il campo `password` senza
|
||||
script; `WebHostTests` che ogni file sia servito con il suo tipo e che l'errore di accesso prenda il posto del
|
||||
segnaposto;
|
||||
- `node --check` su una copia `.mjs` dei moduli toccati, se Node c'è: su un `.js` Node legge uno script e non vede
|
||||
gli errori propri dei moduli, come un `import` che si scontra con un `let` e ferma tutta l'app;
|
||||
- gli screenshot del §10 guardati uno per uno, in entrambi i temi, e la console pulita.
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-0005 — Nessuna approvazione manuale dei singoli ordini
|
||||
|
||||
Data: 2026-09-16. Stato: accettata (decisione dell'utente, D-20).
|
||||
Data: 2026-09-16. Stato: accettata (decisione dell'utente, D-20); **superata in parte da ADR-0010** (5.1): la modalità `Paper` non esiste più (le modalità sono `Demo` e `Live`, e la modalità sceglie anche il conto) e il preset non si cambia più a caldo (si sceglie in Impostazioni ▸ Strategia e vale per i basket nuovi). Resta valida la decisione principale: nessuna approvazione dei singoli ordini.
|
||||
|
||||
## Contesto
|
||||
|
||||
@@ -17,3 +17,7 @@ Restano i gate umani che non riguardano il singolo ordine: la frase `CONFERMO LI
|
||||
- Le regole «mai un ordine reale senza flag e conferma» restano vere a livello di sessione: il reale non parte senza flag e frase.
|
||||
- Le uscite protettive erano già automatiche in ogni modalità; ora lo sono anche le aperture e i take-profit.
|
||||
- Se in futuro servisse una revisione umana, va reintrodotta come modalità esplicita e non come default: la specifica originaria resta documentata qui.
|
||||
|
||||
## Aggiornamento 5.1 (2026-09-30)
|
||||
|
||||
`Paper` è stata eliminata: il conto demo di eToro fa già da simulatore, con le esecuzioni vere. Un file che dice `Paper` si legge come `Demo` con un avviso; le righe storiche del ledger con `mode = Paper` restano. I gate umani che restano sono l'avvio del reale (`run.allowLive` e la frase `CONFERMO LIVE` scritta nell'interfaccia, a ogni avvio: il Live non parte mai da solo), il kill-switch e il reset motivato; il cambio di preset a caldo non c'è più (ADR-0010).
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-0006 — Apprendimento: livello 0 e logistica in ombra restano, MLP, bandit e ciclo settimanale si spengono a runtime
|
||||
|
||||
Data: 2026-09-23. Stato: accettata con il default di D-30 (§8 del piano 5.0); revocabile con una risposta diversa.
|
||||
Data: 2026-09-23. Stato: accettata con il default di D-30 (§8 del piano 5.0); revocabile con una risposta diversa. **Aggiornata da ADR-0014** (5.1): lo stato in ombra e il criterio di riattivazione restano; il ciclo gira in background nel processo con un solo scrittore dei file e l'interfaccia ha la pagina Apprendimento al posto di Impostazioni ▸ Ricerca.
|
||||
|
||||
## Contesto
|
||||
|
||||
@@ -20,3 +20,9 @@ Data: 2026-09-23. Stato: accettata con il default di D-30 (§8 del piano 5.0); r
|
||||
- `strategy.json` cresce della sezione `learning` (`enabled`, `weeklyCycle`, `challenger`); l'hash della configurazione la include.
|
||||
- I file `data/models/*` e `knowledge/*` restano dove sono e vengono letti dallo strumento.
|
||||
- Quando il criterio sarà soddisfatto, la riattivazione passa da una proposta in `knowledge/proposals.csv`, dalla pre-registrazione e da `learning.enabled = true`.
|
||||
|
||||
## Aggiornamento 5.1 (2026-09-30)
|
||||
|
||||
- Il ciclo non vive più solo nello strumento: «Esegui ciclo» nella pagina **Apprendimento** lo esegue in background, nel motore se è acceso o come manutenzione sotto il lock di istanza se è fermo; `backtest learn` resta e prende lo stesso lock (ADR-0014). Il ciclo settimanale nel bot gira solo con `learning.enabled` e `learning.weeklyCycle` accesi, come qui deciso.
|
||||
- Le etichette della 4.0.0-5.0.0 erano i proceeds delle chiusure, non il P&L (ADR-0011): i modelli addestrati su quelle etichette sono stati ritirati e la logistica riaddestrata sulle etichette corrette; il bandit è ripartito dal prior. Il conteggio verso i 300 basket usa solo le righe con il P&L dello storico eToro.
|
||||
- Il bandit premia il preset con cui il basket è entrato, non quello in vigore alla chiusura.
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-0007 — Interfaccia web servita dal bot al posto della finestra WPF
|
||||
|
||||
Data: 2026-09-23. Stato: accettata (risposta dell'utente a D-28: «il bot deve essere eseguito SOLO tramite container. Elimina tutta la parte della grafica Windows»).
|
||||
Data: 2026-09-23. Stato: accettata (risposta dell'utente a D-28: «il bot deve essere eseguito SOLO tramite container. Elimina tutta la parte della grafica Windows»). **Superata in parte** nella 5.1: lo stile Material 3 e la struttura a un solo `app.js` da ADR-0013 (interfaccia in stile Mimante, moduli ES, nove pagine); il token `ENCELADO_WEB_TOKEN`, le chiavi da variabili d'ambiente e il file `etoro.keys.enc` da ADR-0010 (password `ENCELADO_PASSWORD`, segreti in `secrets.enc` cifrati con la password); lo snapshot completo a ogni secondo da ADR-0012 (tick v2 condiviso e sezioni a richiesta). Resta valida la decisione principale: interfaccia web, vanilla, servita dal bot.
|
||||
|
||||
## Contesto
|
||||
|
||||
@@ -27,3 +27,9 @@ Fino alla 4.0.0 Encelado era un'applicazione WPF (`Encelado.exe`, `net10.0-windo
|
||||
- Le regole «una barra in alto, pagine sotto, dettagli nei tooltip» restano; cambia il mezzo. La navigazione diventa un navigation rail a sinistra (80/256 px, stato ricordato).
|
||||
- La bonifica interattiva, il reset in cinque passi, il kill-switch con la spunta «chiudi anche le esterne» e la frase `CONFERMO LIVE` passano da dialoghi HTML.
|
||||
- Chi vuole la finestra non ce l'ha più: si apre il browser su `http://<ip>:8080/`.
|
||||
|
||||
## Aggiornamento 5.1 (2026-09-30)
|
||||
|
||||
- L'interfaccia è stata rifatta nello stile di Mimante (ADR-0013): token propri al posto dei ruoli Material 3, menu a sinistra con nove pagine al posto del rail con quattro, moduli ES statici in `wwwroot/js/` e un foglio di stile per pagina, disegno per celle al posto di `innerHTML`.
|
||||
- L'accesso è con la password dell'interfaccia (`ENCELADO_PASSWORD`, alias deprecato `ENCELADO_WEB_TOKEN`) e il cookie `encelado_session`, un HMAC della password e di un segreto del server (`/config/session.key`); le chiavi eToro dei due conti e il token Telegram stanno in `/config/secrets.enc`, cifrati con la password, e si inseriscono da Impostazioni (ADR-0010). `etoro.keys.enc` e `ENCELADO_KEY_PASSPHRASE` servono solo all'importazione una tantum di un container 5.0.
|
||||
- Il flusso è il tick v2, uno al secondo condiviso da tutti i browser, più le sezioni a richiesta con `ETag` (ADR-0012, `docs/API.md`).
|
||||
@@ -1,6 +1,6 @@
|
||||
# ADR-0008 — Engine + Server, immagine Docker come pacchetto, Unraid come destinazione
|
||||
|
||||
Data: 2026-09-23. Stato: accettata (D-28: «solo tramite container»; D-29: registro dei container di Gitea, icona nel repository).
|
||||
Data: 2026-09-23. Stato: accettata (D-28: «solo tramite container»; D-29: registro dei container di Gitea, icona nel repository). **Superata in parte da ADR-0010** (5.1): il template Unraid ha solo la porta, `/config`, `/data` e la variabile `ENCELADO_PASSWORD`; `PUID`, `PGID` e `TZ` restano default dell'immagine (99, 100, UTC; `TZ` lo aggiunge Unraid da sé) e non stanno più nel template; `/api/info` è diventata un alias di `/api/system`. Restano validi i tre progetti, l'immagine come pacchetto, i volumi, l'entrypoint, l'healthcheck e la catena di rilascio.
|
||||
|
||||
## Contesto
|
||||
|
||||
@@ -29,3 +29,11 @@ Con la finestra WPF ritirata (ADR-0007) il bot ha bisogno di un processo che gir
|
||||
- L'istanza unica per cartella dati (`instance.lock`) vale anche fra un container e un processo locale che montino la stessa cartella.
|
||||
- Un aggiornamento dell'immagine è un riavvio: il recupero dopo inattività (Fase 4) copre il buco.
|
||||
- La catena `build/` cambia struttura rispetto a Mimante/AutoBidder (niente installatore): la differenza è documentata in `build/README.md`.
|
||||
|
||||
## Aggiornamento 5.1 (2026-09-30)
|
||||
|
||||
- **Template**: porta, `/config`, `/data` e «Password interfaccia» (`ENCELADO_PASSWORD`, mascherata e obbligatoria). Conto, chiavi eToro dei due conti, Telegram, valuta, log e avvio automatico si impostano dall'interfaccia (ADR-0010); le variabili di un container 5.0 vengono importate una volta al primo avvio della 5.1 e poi ignorate.
|
||||
- **Healthcheck**: l'heartbeat è vecchio oltre 3 × `recovery.heartbeatSeconds` + 15 s (105 s con il default), non più una soglia fissa (ADR-0012).
|
||||
- **Arresto**: con `run.closeOnShutdown` la chiusura la esegue il motore sul suo thread entro 30 s; un kill-switch in corso ha 30 s per finire. I 45 s di grazia del container li coprono.
|
||||
- **Rete**: il server ascolta su tutte le interfacce solo con la password, nel container; fuori dal container (F5, `run-dev`) solo con `--listen-all`.
|
||||
- Commit e data di build si leggono in Sistema ▸ Informazioni e in `/api/system` (`/api/info` è un alias).
|
||||
@@ -0,0 +1,47 @@
|
||||
# ADR-0010 — Configurazione solo dall'interfaccia, un solo segreto nel container
|
||||
|
||||
Data: 2026-09-30 (aggiornata il 2026-10-01 con le correzioni della revisione 5.1). Stato: accettata (richiesta dell'utente, `Modifiche.txt` del 2026-09-30). Supera in parte ADR-0005 (le modalità), ADR-0007 (chiavi e token dell'interfaccia) e ADR-0008 (le variabili del template).
|
||||
|
||||
## Contesto
|
||||
|
||||
La 5.0.0 si configurava in due posti: il file `encelado.json` (dall'interfaccia) e una dozzina di variabili d'ambiente del container (chiavi eToro, ambiente, modalità, conferma Live, valuta, passphrase, Telegram, porta, PUID/PGID, TZ, avvio automatico). Le variabili vincevano sul file a ogni riavvio: una modalità o una valuta cambiata dall'interfaccia tornava indietro al riavvio successivo del container. L'utente ha chiesto che nel container resti **solo la password dell'interfaccia** e che tutto il resto si imposti dalla pagina.
|
||||
|
||||
L'analisi della superficie di configurazione ha trovato anche tre difetti di sicurezza:
|
||||
|
||||
1. `run.executionMode` e `etoro.environment` erano indipendenti: `Demo` con ambiente `real` mandava ordini sul conto reale **senza** il cancello Live (`allowLive` e la frase).
|
||||
2. La conferma Live restava attiva per sempre dopo il primo avvio (`StartConfirmed` mai azzerato): un riavvio automatico sarebbe entrato in Live senza la frase.
|
||||
3. Nessuna impostazione salvata arrivava al motore fino al riavvio del processo; la pagina mostrava il valore vecchio subito dopo il salvataggio.
|
||||
|
||||
La revisione della 5.1 (2026-09-30/10-01) ha trovato altri buchi nello stesso perimetro: un file 5.0 con `Live` accanto a `demo` (letto Demo) diventava Live al primo salvataggio qualsiasi; la guardia del cambio di conto leggeva la vista pubblicata, che a metà di un ingresso o durante l'avvio sembra piatta; un solo file di stato veniva riscritto dal motore dell'altro conto; una password errata via `Authorization: Bearer` o cookie non costava niente; una pagina di un altro sito poteva mandare un salvataggio con un form; `--sample` leggeva i segreti veri dell'operatore.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Una sola variabile**: `ENCELADO_PASSWORD` («Password interfaccia» nel template Unraid, mascherata e obbligatoria). `ENCELADO_WEB_TOKEN` resta come alias deprecato, così i container 5.0.0 restano raggiungibili dopo l'aggiornamento (con valori diversi vince `ENCELADO_PASSWORD`). Il cookie di sessione `encelado_session` è un HMAC della password e di un segreto del server (`/config/session.key`, 32 byte casuali creati una volta), mai la password; cambiarla, o cancellare `session.key`, chiude tutte le sessioni. Gli script possono mandare `Authorization: Bearer <password>`.
|
||||
2. **Accesso dalla rete** (revisione): il server ascolta su tutte le interfacce solo con una password **e** nel container (o con l'argomento `--listen-all`); F5 e `run-dev` tengono la password per i segreti della sandbox ma restano su localhost. Senza password ascolta solo su localhost e non chiede niente. Una password errata — dal form o dall'header Bearer — costa al suo indirizzo un'attesa che raddoppia (1, 2, 4, 8, 16, poi 30 s); finché dura, nessuna password di quell'indirizzo viene controllata (429), così i tentativi in parallelo non servono. L'attesa è per indirizzo, non globale: un altro computer della rete non può tenere fuori l'operatore dal kill-switch. Il cookie non è un tentativo (seconda revisione): con il segreto del server dentro non si calcola da una password indovinata, quindi uno valido entra anche mentre l'indirizzo aspetta (un tentatore dietro lo stesso NAT, /64 o proxy non tiene fuori una pagina già entrata) e uno sbagliato — una scheda rimasta aperta dopo un cambio di password — riceve 401 subito; prima, con il cookie derivato dalla sola password e contato come tentativo, una scheda vecchia teneva l'indirizzo in attesa e la password giusta riceveva 429 finché restava aperta. Una richiesta che cambia qualcosa deve dire `Content-Type: application/json` (415 altrimenti) e venire dalla stessa origine (`Origin` e `Sec-Fetch-Site`, 403 altrimenti); senza password ogni richiesta con un `Host` diverso da `localhost`, `127.0.0.1` o `[::1]` riceve 403 (DNS rebinding).
|
||||
3. **Segreti cifrati con la password**: le chiavi eToro del conto demo e del conto reale e il token Telegram stanno in `/config/secrets.enc` (AES-256-GCM, chiave PBKDF2-SHA256 600 000 iterazioni dalla password, sale conservato, nonce nuovo a ogni scrittura, intestazione autenticata, file leggibile solo dal proprietario). Senza password (sviluppo) la chiave è un file locale casuale (`secrets.key`), sostituito dalla password appena compare. Se la password cambia il deposito risulta «bloccato»: l'interfaccia offre di sbloccarlo con la password precedente o di ricominciare (il vecchio file resta come `.bak`). Un'intestazione che dichiara meno di 100 000 o più di 10 000 000 iterazioni è un file danneggiato, bloccato prima di derivare qualsiasi chiave. I segreti non entrano mai nell'oggetto di configurazione condiviso: motore e storico ne ricevono una copia privata.
|
||||
4. **Importazione una tantum** dai container 5.0.0: al primo avvio le variabili vecchie vengono portate nel deposito cifrato e in `encelado.json` (`import-5.1.json` registra cosa è stato fatto) — le chiavi nell'ordine di precedenza della 5.0 (ambiente, poi chiavi scritte nel file, poi il vecchio `etoro.keys.enc` con `ENCELADO_KEY_PASSPHRASE`, rinominato `.migrato`), ciascuna solo in uno spazio vuoto; token e chat di Telegram; le impostazioni solo quando differiscono dal valore di fabbrica e il file è ancora di fabbrica. Poi ogni variabile rimasta viene ignorata e segnalata («puoi toglierla dal container») nel log e in Sistema. `TZ` e la conferma Live non vengono mai importate. Il caricatore della configurazione non legge più l'ambiente.
|
||||
5. **Paper eliminata**: il conto demo di eToro fa già da simulatore. Le modalità sono `Demo` e `Live` e **determinano il conto** (demo o reale): `etoro.environment` non esiste più come impostazione. Un file della 5.0 viene letto con la regola di fusione (Live solo se modalità Live **e** ambiente `real`, altrimenti Demo, con un avviso) e, quando un salvataggio o l'importazione tolgono `etoro.environment`, al suo posto viene scritta la modalità che il file intendeva (revisione: prima un `Live` + `demo` diventava Live al primo salvataggio).
|
||||
6. **Cancello Live**: `run.allowLive` più la frase `CONFERMO LIVE` scritta nell'interfaccia, all'avvio e prima di un cambio che riavvia il motore in Live. Nessuna variabile e nessun argomento da riga di comando. **Il Live non parte mai da solo**: né all'avvio del container né dopo un riavvio automatico (allarme e avviso Telegram «premi AVVIA»).
|
||||
7. **Cambio di conto (Demo ↔ Live)** rifiutato finché sul conto in uso c'è qualcosa in sospeso. Dalla revisione: **lo stato è per conto** (`data/state/baskets_state.demo.json` e `baskets_state.live.json`, D-53), quindi un cambio non sovrascrive né scarta niente dell'altro conto; il registro degli ordini resta un file solo, ma ogni motore vede e risolve solo gli ordini del suo conto. Con il motore acceso il controllo lo fa **il motore stesso, sul suo thread di decisione**: prima blocca nuove entrate e aggiunte, poi riconcilia con il conto (seconda revisione: una gamba del bot che nessuno slot tiene, come la gamba A rimasta quando la sua richiusura è rifiutata, compare solo alla riconciliazione successiva, fino a 20 s dopo; se le posizioni non si leggono il cambio è rifiutato), poi conta sui propri basket (posizioni, gambe in attesa, ingressi, aggiunte o uscite in corso, errori con una gamba, ordini senza esito, orfane e residui, chiusure in attesa del P&L). Rifiutato mentre il motore si avvia, si ferma o non risponde in 30 s. Dopo l'arresto, prima di avviare l'altro conto, il file del conto lasciato viene giudicato di nuovo; se non è piatto `encelado.json` e `strategy.json` tornano byte per byte come prima. A motore fermo decide il file del conto in uso.
|
||||
8. **Preset fisso**: si sceglie in Impostazioni ▸ Strategia ed è scritto in `strategy.json`; il comando per cambiarlo a caldo è stato tolto. Un cambio di strategia vale per i basket nuovi: quelli aperti conservano lo z di stop, le aggiunte massime, il TP, la perdita massima e il preset con cui sono entrati.
|
||||
9. **Applicazione a caldo**: dopo ogni salvataggio la configurazione in memoria torna uguale al file e le modifiche si applicano subito (log, Telegram, interfaccia), nel motore sul thread di decisione (strategia, intervalli, timeout; riga `configurazione` nel ledger con il nuovo hash) oppure con un riavvio automatico del motore senza chiudere i basket (modalità, chiavi del conto attivo, coppie dei basket, `preferDirectCross`). Il riavvio passa dal lucchetto del ciclo di vita del supervisore (ADR-0012): riavvia solo un motore ancora acceso (un FERMA arrivato prima vince) e mai a metà di un kill-switch, di una chiusura o della chiusura dei residui (409 prima di scrivere). La risposta dice, campo per campo, cosa è successo.
|
||||
10. **Avvio automatico** come impostazione (`run.autostart`, attiva di fabbrica); `--no-autostart` resta per lo sviluppo.
|
||||
11. **`--sample`** lavora in cartelle temporanee cancellate all'uscita: non legge né scrive configurazione, segreti e dati dell'operatore, non apre il suo bot Telegram; le Impostazioni mostrano i valori di fabbrica e ogni scrittura risponde 400.
|
||||
|
||||
## Alternative scartate
|
||||
|
||||
- **Tenere le variabili come override**: è la causa del «torna indietro al riavvio» e l'utente le vuole fuori.
|
||||
- **Segreti in chiaro in `/config`**: chi legge la share di appdata avrebbe le chiavi del conto.
|
||||
- **Chiave di cifratura casuale salvata accanto ai segreti**: equivalente al chiaro per chi legge `/config`; la password del container non sta su quel volume.
|
||||
- **Riavviare il motore a ogni salvataggio**: interrompe decisioni e riconciliazioni per cambi che non ne hanno bisogno.
|
||||
- **Un solo file di stato con una sezione per conto**: un motore avrebbe comunque riscritto il file intero, e un errore di scrittura avrebbe toccato anche l'altro conto. Due file, ciascuno scritto solo dal suo motore, non si toccano mai.
|
||||
- **Attesa dopo una password errata unica per tutto il server**: chiunque nella rete potrebbe tenerla accesa e lasciare l'operatore fuori dall'interfaccia, kill-switch compreso.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Il template Unraid ha la porta, le due cartelle e la password; nient'altro. `TZ` lo aggiunge Unraid da sé (vale solo per gli orari mostrati dal server e nel log); PUID/PGID restano 99/100 nell'immagine.
|
||||
- Cambiare la password del container obbliga a sbloccare i segreti con quella vecchia o a reinserirli. Rinominare `ENCELADO_WEB_TOKEN` in `ENCELADO_PASSWORD` con lo stesso valore li lascia leggibili.
|
||||
- Un container Live che si riavvia resta fermo finché qualcuno non preme AVVIA: le posizioni aperte hanno solo gli stop nativi nel frattempo.
|
||||
- Dietro un reverse proxy l'attesa dopo una password errata vale per tutti i client che il proxy fa sembrare uno; il proxy deve passare l'`Host` originale (o `X-Forwarded-Host`), altrimenti ogni salvataggio riceve 403.
|
||||
- Le righe storiche del ledger con `mode = Paper` restano come sono.
|
||||
- Il primo avvio dopo l'aggiornamento migra il file di stato unico una volta sola (resta come `.migrato`): un file della 5.1 al conto del suo `mode`; uno della 5.0, il cui `mode` è la modalità e non il conto, al conto su cui operava la configurazione della 5.0, che l'importazione registra in `import-5.1.json` (`legacyState`: un `Live` accanto a `demo` è il conto demo, un `Demo` accanto a `real` il reale). Lo stato di Paper, o scritto con un'altra modalità, non viene ripreso (seconda revisione: un file `Live` del conto demo finiva al conto reale e il suo saldo diventava un «prelievo»).
|
||||
@@ -0,0 +1,36 @@
|
||||
# ADR-0011 — Il realizzato viene dallo storico di eToro
|
||||
|
||||
Data: 2026-09-30 (aggiornata il 2026-10-01 con le correzioni della revisione 5.1). Stato: accettata.
|
||||
|
||||
## Contesto
|
||||
|
||||
L'utente ha segnalato un «P&L oggi» di circa 47 000 USD su un'equity di 139 000. La causa: dalla 4.0.0 l'esito di una chiusura (`GET …/close-orders/{orderId}`) veniva letto dal campo `proceeds`, che per eToro è il denaro restituito al conto (margine liberato più profitto), non il profitto. Verificato sul conto demo: dal 23/9 al 30/9 il bot ha chiuso 102 posizioni con un risultato netto di **−269,42 USD**, mentre la somma di investimento più profitto delle stesse chiusure superava i 903 000 USD; il 24/9, sei chiusure con +48,34 USD di netto contavano come circa 53 900 USD.
|
||||
|
||||
Lo stesso numero finiva nel «P&L oggi», nelle righe di `baskets.csv` e quindi nelle etichette dell'apprendimento (quasi tutte «vinto»), nei premi del bandit, nei messaggi Telegram e nel controllo della perdita giornaliera, che dopo la prima chiusura del giorno non poteva più scattare. La pagina Storico era giusta: legge lo storico di eToro.
|
||||
|
||||
La risposta della chiusura non ha un campo di profitto (verificato sulla specifica dell'API v1.383): ha `proceeds` e, per posizione, prezzo, unità, tasso di conversione e importo chiuso.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Il realizzato di una posizione è quello dello storico di eToro**: `netProfit − fees` della riga con lo stesso `positionId` (l'`orderId` dello storico è l'ordine di apertura, non la chiusura). È la stessa fonte della pagina Storico. `proceeds` non diventa mai P&L.
|
||||
2. **Stima provvisoria** dalla risposta della chiusura (unità × differenza di prezzo × tasso di conversione − costi), verificata contro lo storico su tre operazioni reali al centesimo. Serve solo finché lo storico non conferma.
|
||||
3. **Coda di regolamento** persistente nello stato del motore: la riga di `baskets.csv` viene scritta con il numero dello storico quando conferma; dopo 30 minuti senza conferma viene scritta la stima, marcata «P&L: stima», che non addestra mai i modelli. **Una posizione, una riga** (revisione): una posizione già scritta in `baskets.csv` o già in coda non viene registrata di nuovo da nessun percorso (uscita del basket, residuo del kill-switch, riconciliazione, orfana richiusa); le gambe di un basket rimaste nel residuo di un kill-switch diventano una riga sola, come basket, quando sono tutte chiuse.
|
||||
4. **«P&L oggi»** = somma di `netProfit − fees` delle posizioni **del bot** chiuse nella giornata UTC, ricalcolata dallo storico (più le stime non ancora confermate, segnalate). È uguale al periodo «oggi» della pagina Storico. Accanto: la variazione dell'equity netta da mezzanotte (realizzato più variazione dell'aperto, movimenti di cassa esclusi). Sconosciuto (storico non ancora letto) = «—», mai 0.
|
||||
5. **Perdita giornaliera** = calo dell'equity netta dalle 00:00 UTC rispetto a quella di inizio giornata, come nel backtest e in `docs/RISK_RULES.md`; una funzione sola per motore e backtest. **Raggiunta una volta, blocca nuove entrate e aggiunte fino alle 00:00 UTC anche se l'equity risale** (D-52, revisione: prima il blocco cadeva appena l'equity tornava sopra la soglia, mentre interfaccia e ledger promettevano «fino a domani»). Il giorno del blocco è nello stato del conto e sopravvive a un riavvio. Un calo del saldo che lo storico non spiega ancora (forse un prelievo) sospende subito le entrate ma blocca la giornata solo quando risulta una perdita (D-54); la sospensione dura finché lo storico non lo spiega, anche se intanto l'equity recupera, e quella lettura giudica la giornata sull'equity più bassa vista nel frattempo, contando un prelievo come uscito prima del minimo e un deposito come arrivato dopo (seconda revisione: una perdita spiegata dopo un recupero non bloccava più la giornata).
|
||||
6. **Saldo all'avvio** (revisione): il saldo salvato si giudica — chiusure contro movimenti di cassa — solo quando lo storico mostra ogni posizione chiusa da allora; altrimenti resta il riferimento e giudica la riconciliazione che la vede, come in sessione. Una chiusura non ancora nello storico non viene mai scritta come prelievo.
|
||||
7. **Correzione del passato senza toccare il ledger**: all'avvio, sul conto in uso, una verifica idempotente ritrova il realizzato vero di ogni riga scritta dalla 4.0.0/5.0.0 e aggiunge righe `correzione` (tipo `pnl_realizzato`) in `decisions.jsonl`; un lettore corretto le applica; la feature `lastNOutcomes`, calcolata sulle etichette sbagliate, viene neutralizzata (0,5) per le righe precedenti alla correzione; i modelli addestrati su quelle etichette vengono ritirati (messi da parte in `data/models/ritirati/`), la logistica viene riaddestrata sulle etichette corrette e il bandit riparte dal prior. Dalla revisione la verifica tiene una soglia **per conto** (la nota `verifica_realizzato` porta `mode`; le modalità 4.0 `LiveAuto`/`LiveApprove` contano come Live), abbina ogni gamba singola della 4.0-5.0 alla sua nota solo per stesso `basket_id`, una nota per riga e in ordine di tempo (un abbinamento ambiguo lascia la riga non verificabile invece di indovinare), e il ritiro dei modelli è tutto o niente. Le righe dell'altro conto si correggono quando quel conto gira: quell'avvio, se il ritiro c'è già stato, neutralizza di nuovo `lastNOutcomes` fino ad allora e rifà la sola logistica (seconda revisione).
|
||||
8. Una lettura dello storico fallita è un errore, mai un elenco vuoto: nessuna chiusura viene contata 0 per un problema di rete.
|
||||
|
||||
## Alternative scartate
|
||||
|
||||
- **`proceeds` meno l'importo investito**: semantica non documentata, costi non chiari, non copre le chiusure fatte dagli stop nativi o a mano.
|
||||
- **Accumulare il realizzato chiusura per chiusura**: si perde le chiusure non fatte dal bot (stop nativi, chiusure manuali), può contare due volte dopo un riavvio e si allontana dalla pagina Storico.
|
||||
- **Riscrivere `baskets.csv`**: vietato (il ledger non si modifica mai).
|
||||
- **Rivalutare la perdita giornaliera a ogni decisione** (come faceva la prima 5.1 e il backtest): un'equity che oscilla intorno alla soglia apriva e chiudeva il blocco più volte al giorno; il blocco fino a mezzanotte è la regola scritta ed è la più prudente.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Una lettura dello storico in più ogni tanto (quota Default, circa 0,2-1 al minuto contro 55 disponibili).
|
||||
- I messaggi Telegram e le righe di log già inviati con i valori sbagliati restano sbagliati: lo dice la cronologia.
|
||||
- Il primo avvio della 5.1 scrive le correzioni e ritira i modelli; il ciclo di apprendimento successivo rigenera calibrazione e intuizioni. Un'installazione che aveva già fatto la verifica con la prima 5.1 (nota senza `mode`) la ripete una volta, senza effetti, e scrive una nota per conto.
|
||||
- Il backtest applica lo stesso blocco fino a mezzanotte (`ReplayDailyLoss`): i numeri di `docs/STRATEGY.md` §3, fatti prima, vanno rifatti insieme ai limiti di margine.
|
||||
@@ -0,0 +1,38 @@
|
||||
# ADR-0012 — Il motore pubblica viste immutabili; un solo tick condiviso per tutti i browser; un solo lucchetto per il ciclo di vita
|
||||
|
||||
Data: 2026-09-30 (aggiornata il 2026-10-01 con le correzioni della revisione 5.1: il lucchetto del ciclo di vita e la chiusura all'arresto sul thread di decisione). Stato: accettata.
|
||||
|
||||
## Contesto
|
||||
|
||||
L'utente ha trovato l'interfaccia della 5.0 «lenta e pesante» e ha chiesto che non rallentasse il bot. L'analisi ha trovato:
|
||||
|
||||
- ogni browser aperto faceva costruire e serializzare al server lo snapshot completo una volta al secondo (N schede = N costruzioni al secondo), con dentro 200 righe di log (35-45 KB a tick);
|
||||
- la costruzione dello snapshot leggeva dal thread web lo stato del thread di decisione senza sincronizzazione (righe incoerenti, possibili eccezioni «collection was modified»), prendeva cinque lock usati anche dal motore e aveva effetti collaterali: chiedeva una previsione di volatilità che finiva in una coda mai svuotata e cambiava il modello di volatilità attivo, che a sua volta scala la soglia di ingresso;
|
||||
- il browser ricostruiva con `innerHTML` tabelle e liste intere a ogni tick, su ogni pagina e anche a scheda nascosta;
|
||||
- il ciclo di decisione aspettava il download di tredici feed.
|
||||
|
||||
La revisione della 5.1 ha trovato lo stesso problema nel ciclo di vita del motore: un FERMA arrivato mentre AVVIA (o un riavvio automatico delle impostazioni) costruiva il motore dichiarava il bot fermo e lasciava un motore che operava senza che kill-switch, FERMA e comandi lo raggiungessero; un riavvio automatico poteva annullare un FERMA arrivato prima; un comando in coda a un motore che si fermava aspettava 120 s e rispondeva 500; con `closeOnShutdown` il supervisore chiamava la chiusura del motore dal proprio thread, in concorrenza con il ciclo di decisione.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Il thread di decisione pubblica viste immutabili** (`Volatile.Write`) alla fine di ogni giro, dopo le quotazioni, le transizioni, i comandi e le riconciliazioni. Il thread web legge solo quelle. Costruire una vista non ha effetti collaterali.
|
||||
2. **Un solo tick al secondo, condiviso**: il server serializza una volta sola e manda gli stessi byte a tutti i client SSE; se nessuno è connesso non calcola niente; un client lento riceve solo l'ultimo tick.
|
||||
3. **Tick piccolo**: le righe di log sono solo quelle nuove dall'ultimo tick; le sezioni pesanti (posizioni, mercato, sistema, dettaglio basket, apprendimento) sono rotte a richiesta con `ETag`, rilette dal browser solo quando il loro numero di versione nel tick cambia.
|
||||
4. **Il browser** aggiorna solo la pagina visibile, una volta per frame, cella per cella (righe con chiave, nessun `innerHTML` per i dati), con formattatori in cache; chiude lo stream quando la scheda resta nascosta.
|
||||
5. **I feed (calendario, notizie) si aggiornano in background** e appartengono al processo: il ciclo di decisione non aspetta più la rete dei feed, e la pagina Mercato resta aggiornata anche a motore fermo.
|
||||
6. **Nessun metodo del motore si chiama da un altro thread** (revisione): tutto ciò che cambia lo stato del motore è un comando eseguito sul thread di decisione, compresa la chiusura all'arresto (`run.closeOnShutdown`: comando `Shutdown`, che prima blocca nuove entrate e aggiunte, poi chiude basket, gambe in attesa e orfane entro 30 s, e solo dopo il ciclo viene annullato), il controllo del cambio di conto (ADR-0010) e l'applicazione delle impostazioni. Ogni comando riceve una risposta: quelli rimasti in coda o interrotti da un arresto rispondono subito «comando interrotto: il motore si è fermato» e finiscono nel ledger; un'attesa scaduta è 504 con un messaggio, mai 500.
|
||||
7. **Un solo lucchetto per il ciclo di vita** (revisione): il supervisore serializza avvio, arresto, riavvio automatico, rilascio di un motore in errore e ciclo di apprendimento a motore fermo, ciascuno dal primo controllo all'ultimo cambio di stato. Ogni avvio ha un numero di generazione e un arresto pulisce solo il motore che ha fermato; lo stato resta «stopping» finché il motore vecchio non ha lasciato il lock di istanza, così AVVIA subito dopo FERMA aspetta invece di fallire. Un kill-switch, una chiusura, la chiusura dei residui o una chiusura della bonifica in coda o in corso non vengono mai tagliati: FERMA e i salvataggi che riavvierebbero il motore rispondono 409, finché il motore li ha in mano — li conta lui stesso, dalla coda alla fine sul thread di decisione, non il chiamante, che può andarsene (scheda chiusa, 504 dopo 120 s, poller Telegram fermato: seconda revisione); solo l'arresto del processo li interrompe dopo 30 s, e un kill-switch interrotto registra il residuo (Halted-Residuo) invece di un blocco pulito.
|
||||
8. **Il controllo di salute segue il battito che il motore pubblica**: l'intervallo dell'heartbeat (`recovery.heartbeatSeconds`, cambiabile a caldo) viaggia nella vista; `/api/health` dà l'allarme oltre 3 × intervallo + 15 s.
|
||||
|
||||
## Alternative scartate
|
||||
|
||||
- **Lock condivisi fra web e motore**: ogni lettura della pagina rallenterebbe il ciclo di decisione, ed è il problema che si voleva togliere.
|
||||
- **Un `CancellationToken` per interrompere i comandi critici**: un kill-switch tagliato a metà lascia posizioni senza nessuno che le guardi; meglio rifiutare il FERMA e lasciar finire.
|
||||
- **WebSocket al posto di SSE**: un canale bidirezionale non serve (i comandi sono POST) e porterebbe uno stato per connessione.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Da N a 1 costruzioni al secondo (0 senza browser aperti); tick da ~40 KB a pochi KB.
|
||||
- Il formato del tick cambia (v2, `docs/API.md`): l'interfaccia 5.0 non è compatibile.
|
||||
- Un campo nuovo dello stato passa dalla vista pubblicata, non da una lettura diretta dal thread web.
|
||||
- FERMA durante un kill-switch risponde 409 e va ripetuto quando il kill-switch è concluso; `docker stop` concede 30 s a un kill-switch in corso (il container ne ha 45 di grazia).
|
||||
@@ -0,0 +1,43 @@
|
||||
# ADR-0013 — Interfaccia in stile Mimante
|
||||
|
||||
Data: 2026-09-30. Stato: accettata (richiesta dell'utente, `Modifiche.txt` del 2026-09-30). Modifica ADR-0007: l'interfaccia resta web, vanilla e servita dal bot; cambiano il linguaggio visivo, la struttura dei file e il modo di disegnare.
|
||||
|
||||
## Contesto
|
||||
|
||||
L'interfaccia della 5.0 (un solo `app.js` e un solo `app.css` in stile Material 3, quattro pagine con un navigation rail) era, per l'utente, «lenta e pesante», e lui non voleva che la grafica rallentasse il bot. Ha chiesto di rivederla completamente con lo stile del suo altro progetto, Mimante (`C:\Sviluppo\Mimante\Mimante`), e ha elencato cosa non andava:
|
||||
|
||||
- una dashboard compatta che riassuma tutto in una schermata, con altre schede che approfondiscono ogni parte (lo stato di Telegram e il dettaglio del collegamento eToro escono dalla dashboard);
|
||||
- layout fluido, senza larghezza massima e senza la fascia grigia a destra;
|
||||
- controlli allineati e della stessa altezza (nel Log «Segui» non era allineato con il filtro e la ricerca);
|
||||
- niente selettore della valuta nella barra in alto (solo in Impostazioni);
|
||||
- niente scritte «in esecuzione» e «demo» in fondo alla barra laterale: altrove, anche con simboli;
|
||||
- un solo orologio per paese delle valute trattate, con le bandiere, più il fuso del computer solo se diverso (D-49), al posto di UTC + fuso;
|
||||
- il log con il livello come etichetta colorata e ogni messaggio su una riga;
|
||||
- una pagina dedicata all'apprendimento.
|
||||
|
||||
La lentezza aveva anche cause sul server (ADR-0012): lo snapshot completo ricostruito per ogni browser ogni secondo. La parte del browser era il ridisegno con `innerHTML` di tabelle intere a ogni tick, su ogni pagina e anche a scheda nascosta.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Resta ADR-0007**: HTML, CSS e JavaScript vanilla, incorporati nell'assembly e serviti dal bot; nessun framework, nessuna libreria, nessun CDN, nessun font remoto, nessun `@import` né `import()` dinamico.
|
||||
2. **Linguaggio visivo di Mimante**: token in `css/tokens.css` (tema scuro predefinito, chiaro con gli stessi nomi), colore solo dai token e con un significato (neutro secondario, accento primario, verde/ambra/rosso per ok/attenzione/pericolo, oro per il notevole), testo a 13 px con cifre tabulari, controlli alti 30 px, barra in alto di 46 px, menu a sinistra di 212/56 px con icone, nessuna `max-width`, tooltip su ogni numero, niente toast (una finestra al centro solo per errori, conferme e risultati importanti), bottoni a icona con `title` e `aria-label`.
|
||||
3. **Struttura a moduli ES**: `index.html` è solo lo scheletro (XHTML ben formato), `js/app.js` importa staticamente gli altri moduli (`state`, `stream`, `util`, `grid`, `ui`, `charts`, `dialog`, `actions`, `baskets`, `labels`, `icons`, `flags`, `clocks`, `split`) e una pagina per file in `js/pages/`; un foglio di stile per pagina in `css/pages/`. `login.html` non ha script (`/js/*` chiede la sessione). Ogni file sotto `wwwroot/` è servito al suo percorso con `ETag` e 304.
|
||||
4. **Nove pagine**: Dashboard (tutto in una schermata a 1440×900), Basket, Posizioni, Mercato, Storico, Apprendimento, Log, Sistema, Impostazioni, più la pagina di accesso. Lo stato del motore e il conto sono la pill nella barra in alto; gli allarmi una striscia sotto la barra.
|
||||
5. **Disegno**: un solo store alimentato dal tick (ADR-0012); solo la pagina visibile disegna, una volta per frame; righe con chiave e aggiornamento per cella; nessun `innerHTML` con dati; formattatori `Intl` in cache; lo stream si chiude dopo 15 s di scheda nascosta.
|
||||
6. **Parole del ledger in italiano**: evento, codici di motivo, motivi d'uscita, stati degli ordini, sorgenti del log passano da `js/labels.js`; il codice resta nel tooltip.
|
||||
|
||||
Le regole complete sono in `docs/UI_GUIDELINES.md`; il contratto dei dati in `docs/API.md`.
|
||||
|
||||
## Alternative scartate
|
||||
|
||||
- **Tenere Material 3 e correggere solo le prestazioni**: l'utente ha chiesto lo stile di Mimante, e il ridisegno per celle richiedeva comunque di riscrivere ogni pagina.
|
||||
- **Un framework (React, Vue, Svelte) o una libreria di componenti**: contro la regola «nessuna libreria» e con una catena di build npm da mantenere.
|
||||
- **Pagine caricate con `import()` dinamico**: il primo caricamento sarebbe più leggero, ma i test dell'HTML incorporato (che controllano ogni `import` e i nomi esportati) e la regola «nessun caricamento nascosto» lo escludono; il peso misurato a runtime è comunque piccolo.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Circa 295 KB di JavaScript non minificato (circa 90 KB con gzip) e 60 KB di CSS, sopra l'obiettivo di 150 KB: pesano i tooltip in italiano, le etichette del ledger e le nove pagine importate staticamente. Kestrel non comprime i file statici (possibile miglioramento).
|
||||
- Lavoro del thread principale misurato sul server vero: circa 64 ms ogni 10 s sulla dashboard, heap fra 1,5 e 2,1 MB.
|
||||
- `EmbeddedUiTests` controlla ogni `import` statico e i nomi esportati: un nome mancante fermerebbe tutta l'app con un `SyntaxError`.
|
||||
- Le foto in `docs/img/` si rifanno con `scripts/screenshots.ps1|.sh` (Edge headless; la foto da telefono passa dal protocollo DevTools perché Edge per desktop non stringe la finestra sotto circa 500 px).
|
||||
- L'interfaccia della 5.0 non è compatibile con il tick v2 e non esiste più.
|
||||
@@ -0,0 +1,34 @@
|
||||
# ADR-0014 — Ciclo di apprendimento in background, con un solo scrittore dei file
|
||||
|
||||
Data: 2026-09-30 (aggiornata il 2026-10-01 con le correzioni della revisione 5.1). Stato: accettata. Aggiorna ADR-0006: lo stato in ombra e il criterio di riattivazione restano; cambia dove e come gira il ciclo.
|
||||
|
||||
## Contesto
|
||||
|
||||
L'utente ha chiesto una pagina con «le informazioni sull'apprendimento in corso e su ciò che è stato imparato, raccogliendo e mostrando più dati possibile», con un comando per eseguire il ciclo. Nella 5.0 il ciclo aveva quattro difetti che una pagina avrebbe reso evidenti:
|
||||
|
||||
- **due scrittori**: «Esegui ciclo» (Impostazioni ▸ Ricerca) con il bot acceso girava nel processo accanto al motore e riscriveva gli stessi file dei modelli (`data/models`, `knowledge/`): aggiornamenti persi, JSON scritti a metà che alla lettura successiva azzeravano il modello, versioni duplicate, e il motore che non ricaricava mai il modello nuovo;
|
||||
- **ciclo sul thread di decisione**: il ciclo settimanale addestrava con il lock dell'apprendimento preso, fermando quotazioni e uscite per tutta la durata;
|
||||
- **risultati buttati**: il ciclo calcolava AUC con intervallo, Brier, calibrazione, P&L filtrato, Sharpe e DSR e ne teneva una riga di testo;
|
||||
- **file scritti da chi non doveva**: un motore rifiutato dal lock di istanza (un secondo bot sulla stessa cartella) salvava comunque lo stato dell'apprendimento all'uscita; l'MLP challenger veniva addestrato anche con `learning.challenger` spento.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Un solo scrittore** di `data/models` e `knowledge/`: chi tiene il lock di istanza della cartella dati (`data/state/instance.lock`). Il motore costruisce lo stato dell'apprendimento solo dopo aver preso il lock e lo salva, sotto il suo lock, prima di rilasciarlo; un motore rifiutato dal lock non scrive niente. A motore fermo il ciclo gira come **manutenzione** che prende lo stesso lock (AVVIA risponde 409 finché dura); lo strumento `backtest learn` lo prende o si rifiuta con il nome di chi lo tiene.
|
||||
2. **Il ciclo è una funzione pura in background** (`LearningCycle.Train`): legge il ledger in condivisione, senza esserne lo scrittore, e restituisce modelli, valutazione e base di conoscenza senza toccare niente; si interrompe fra un fold, un seme o un'epoca e l'altro quando il motore si ferma. Il thread di decisione lo **applica** fra due tick in pochi millisecondi (`LearningState.Apply`): sostituisce i modelli, rigioca sui modelli nuovi i basket chiusi mentre il ciclo si addestrava, aumenta la versione, scrive ogni file intero (`.tmp` con nome unico e rinomina, `AtomicFile`). Il ciclo settimanale usa lo stesso percorso.
|
||||
3. **«Esegui ciclo»** (`POST /api/commands/learn`): motore acceso → comando al motore, risposta immediata, avanzamento nella pagina; motore fermo o in errore → manutenzione sotto il lock; rifiutato (409) con un ciclo già in corso, con il motore che si avvia (finché il ciclo di decisione non è partito) o si ferma, o con il lock tenuto da un altro processo.
|
||||
4. **La valutazione non si butta**: `data/models/last_cycle.json` tiene la valutazione completa di ogni ciclo (logistica e challenger) e il riepilogo del dataset; la pagina la mostra.
|
||||
5. **La pagina non scrive**: a motore acceso il thread di decisione pubblica un rapporto immutabile (a ogni chiusura di barra e di basket, dopo un ciclo e un comando, all'avvio e ogni minuto); a motore fermo lo stesso rapporto si legge dai file in sola lettura (`LearningDiskReader`: nessuna cartella creata, file aperti in condivisione, righe a metà scartate, mai un `Ledger` o un `LearningState` costruiti).
|
||||
6. **Correzioni della revisione** sullo stesso principio: il ritiro dei modelli addestrati sui proceeds (ADR-0011) è tutto o niente (i file si spostano prima, i modelli si sostituiscono dopo; una riga del registro che non si scrive non fa ripetere il ritiro); dopo la verifica del realizzato all'avvio il motore rilegge dal ledger corretto gli esiti di `lastNOutcomes` e il conteggio dei basket etichettati, anche se il ritiro fallisce; una `p_ML` viaggia con i contributi e l'intercetta del modello che l'ha data, salvati con l'ingresso in `learning_state.json`, così la pagina non spiega mai una p con un modello che non l'ha prodotta.
|
||||
|
||||
## Alternative scartate
|
||||
|
||||
- **Tenere il ciclo solo nello strumento `backtest learn`** (come diceva ADR-0006): con il bot acceso il lock lo impedisce, e chiedere all'operatore di fermare il bot per addestrare un modello in ombra è sproporzionato.
|
||||
- **Un lock dei file condiviso fra il motore e un secondo scrittore**: due processi che scrivono gli stessi file restano due scrittori; un'applicazione sbagliata a metà resterebbe possibile.
|
||||
- **Addestrare sul thread di decisione, ma più in fretta**: con 5 fold, 5 semi e l'early stopping dell'MLP la durata non è prevedibile, e quotazioni e uscite non devono mai aspettare un modello in ombra.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Il ciclo settimanale gira nel bot solo con `learning.enabled` e `learning.weeklyCycle` accesi (ADR-0006 resta: di fabbrica tutto in ombra); «Esegui ciclo» funziona in ogni stato.
|
||||
- Con il bot acceso `backtest learn` sulla stessa cartella si rifiuta: si usa «Esegui ciclo».
|
||||
- `learning_state.json` passa allo schema 2 (legge quello della 5.0; le coppie dell'AUC mobile calcolate con la p ricalcolata alla chiusura vengono scartate alla prima lettura).
|
||||
- Un ciclo a motore fermo tiene AVVIA in attesa per qualche secondo (409 con il motivo).
|
||||
|
After Width: | Height: | Size: 145 KiB |
|
After Width: | Height: | Size: 127 KiB |
|
After Width: | Height: | Size: 180 KiB |
|
Before Width: | Height: | Size: 126 KiB After Width: | Height: | Size: 178 KiB |
|
Before Width: | Height: | Size: 131 KiB After Width: | Height: | Size: 159 KiB |
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 182 KiB |
|
After Width: | Height: | Size: 11 KiB |
|
After Width: | Height: | Size: 164 KiB |
|
Before Width: | Height: | Size: 59 KiB After Width: | Height: | Size: 75 KiB |
|
After Width: | Height: | Size: 95 KiB |
|
After Width: | Height: | Size: 124 KiB |
|
Before Width: | Height: | Size: 52 KiB After Width: | Height: | Size: 164 KiB |
@@ -0,0 +1,40 @@
|
||||
// A screenshot at a true device size through the DevTools protocol of a headless Edge/Chrome, for
|
||||
// scripts/screenshots.sh: desktop Edge will not make a window narrower than about 500 px, so
|
||||
// --window-size=420,860 would photograph a 500 px page cut on the right. Node 22+ (global fetch
|
||||
// and WebSocket), no packages. scripts/screenshots.ps1 does the same in PowerShell.
|
||||
// node scripts/cdp-shot.mjs <browser> <url> <out.png> <width> <height> <profileDir>
|
||||
import { spawn } from 'node:child_process';
|
||||
import { writeFileSync } from 'node:fs';
|
||||
|
||||
const [browser, url, out, width, height, profile] = process.argv.slice(2);
|
||||
const port = 9300 + Math.floor(Math.random() * 500);
|
||||
const proc = spawn(browser, ['--headless=new', '--disable-gpu', '--no-first-run', '--no-default-browser-check', '--hide-scrollbars', '--disable-extensions',
|
||||
`--remote-debugging-port=${port}`, `--user-data-dir=${profile}`, 'about:blank'], { stdio: 'ignore' });
|
||||
const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
|
||||
let code = 1;
|
||||
try {
|
||||
let target = null;
|
||||
for (let i = 0; i < 60 && !target; i++) {
|
||||
await sleep(250);
|
||||
try { target = (await (await fetch(`http://127.0.0.1:${port}/json/list`)).json()).find(t => t.type === 'page'); } catch { /* not up yet */ }
|
||||
}
|
||||
if (!target) throw new Error(`il browser non espone il protocollo DevTools sulla porta ${port}`);
|
||||
const ws = new WebSocket(target.webSocketDebuggerUrl);
|
||||
await new Promise((resolve, reject) => { ws.onopen = resolve; ws.onerror = reject; });
|
||||
let id = 0;
|
||||
const pending = new Map();
|
||||
ws.onmessage = ev => { const m = JSON.parse(ev.data); if (m.id && pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id); } };
|
||||
const send = (method, params = {}) => new Promise(resolve => { const i = ++id; pending.set(i, resolve); ws.send(JSON.stringify({ id: i, method, params })); });
|
||||
await send('Emulation.setDeviceMetricsOverride', { width: Number(width), height: Number(height), deviceScaleFactor: 1, mobile: true });
|
||||
await send('Page.navigate', { url });
|
||||
await sleep(4000);
|
||||
const shot = await send('Page.captureScreenshot', { format: 'png' });
|
||||
writeFileSync(out, Buffer.from(shot.result.data, 'base64'));
|
||||
ws.close();
|
||||
code = 0;
|
||||
} catch (e) {
|
||||
console.error(e.message);
|
||||
} finally {
|
||||
proc.kill();
|
||||
process.exit(code);
|
||||
}
|
||||
@@ -4,14 +4,15 @@
|
||||
|
||||
.DESCRIPTION
|
||||
Stessa disposizione del container: deploy/local/config (encelado.json, strategy.json,
|
||||
chiavi cifrate) e deploy/local/data (ledger, stato, log). La cartella è ignorata da git.
|
||||
Senza ENCELADO_WEB_TOKEN il server ascolta solo su localhost e non chiede il login.
|
||||
Le chiavi eToro: variabili ETORO_API_KEY/ETORO_USER_KEY già nell'ambiente, oppure
|
||||
Impostazioni ▸ Chiavi eToro con ENCELADO_KEY_PASSPHRASE impostata.
|
||||
segreti cifrati) e deploy/local/data (ledger, stato, log). La cartella è ignorata da git.
|
||||
La password dell'interfaccia è "sviluppo", come nel compose: i segreti cifrati della
|
||||
sandbox restano leggibili in entrambi i modi. La password serve ai segreti, non apre la
|
||||
rete: il server ascolta solo su localhost (la rete solo nel container o con --listen-all).
|
||||
Conto, chiavi eToro dei due conti e Telegram si impostano da Impostazioni nella pagina.
|
||||
|
||||
scripts\run-dev.ps1 # motore fermo: premi AVVIA nella pagina
|
||||
scripts\run-dev.ps1 -Autostart # motore avviato subito (servono le chiavi)
|
||||
scripts\run-dev.ps1 -Sample # dati finti, nessuna chiave: per guardare le pagine
|
||||
scripts\run-dev.ps1 -Sample # dati finti in cartelle temporanee: la sandbox, i segreti e Telegram non vengono toccati
|
||||
scripts\run-dev.ps1 -Port 8090
|
||||
#>
|
||||
param(
|
||||
@@ -27,6 +28,7 @@ Set-Location $root
|
||||
$env:ENCELADO_CONFIG_DIR = Join-Path $root "deploy\local\config"
|
||||
$env:ENCELADO_DATA_DIR = Join-Path $root "deploy\local\data"
|
||||
$env:ENCELADO_WEB_PORT = "$Port"
|
||||
$env:ENCELADO_PASSWORD = "sviluppo"
|
||||
New-Item -ItemType Directory -Force $env:ENCELADO_CONFIG_DIR, $env:ENCELADO_DATA_DIR | Out-Null
|
||||
|
||||
dotnet build src/Encelado.Server -c Debug -nologo -v q
|
||||
@@ -35,8 +37,9 @@ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||||
$args = @()
|
||||
if ($Sample) { $args += "--sample" } elseif (-not $Autostart) { $args += "--no-autostart" }
|
||||
$url = "http://localhost:$Port/"
|
||||
Write-Host "Encelado in locale: $url (configurazione in deploy\local\config, dati in deploy\local\data)" -ForegroundColor Cyan
|
||||
Write-Host "Comandi da tastiera: status, close <basket>, kill, residuo, preset <nome>, reset <motivazione>, bonifica, stop. Ctrl+C = arresto." -ForegroundColor DarkGray
|
||||
$where = if ($Sample) { "campione: cartelle temporanee, deploy\local non viene letto" } else { "configurazione in deploy\local\config, dati in deploy\local\data" }
|
||||
Write-Host "Encelado in locale: $url password: quella della sandbox, sviluppo (solo localhost; $where)" -ForegroundColor Cyan
|
||||
Write-Host "Comandi da tastiera: status, close <basket>, kill, residuo, reset <motivazione>, bonifica, stop. Ctrl+C = arresto." -ForegroundColor DarkGray
|
||||
if (-not $NoBrowser) { Start-Job -ScriptBlock { param($u) Start-Sleep -Seconds 3; Start-Process $u } -ArgumentList $url | Out-Null }
|
||||
|
||||
dotnet src/Encelado.Server/bin/Debug/net10.0/Encelado.Server.dll @args
|
||||
@@ -2,14 +2,18 @@
|
||||
# Builds and starts Encelado locally, without the container, in the deploy/local sandbox
|
||||
# (deploy/local/config as /config, deploy/local/data as /data; ignored by git).
|
||||
# sh scripts/run-dev.sh # engine stopped: press AVVIA in the page
|
||||
# sh scripts/run-dev.sh --sample # fake data, no keys: to look at the pages
|
||||
# sh scripts/run-dev.sh --sample # fake data in throwaway folders: the sandbox, its secrets and Telegram are not touched
|
||||
# sh scripts/run-dev.sh --autostart # engine started at once (keys needed)
|
||||
# Without ENCELADO_WEB_TOKEN the server listens on localhost only and asks no login.
|
||||
# The interface password is "sviluppo", as in docker-compose.yml: the encrypted secrets of
|
||||
# the sandbox (eToro keys, Telegram token, entered from Impostazioni) stay readable both ways.
|
||||
# The password is for the secrets, not for the network: the server listens on localhost only
|
||||
# (the network only in the container or with --listen-all).
|
||||
set -eu
|
||||
cd "$(dirname "$0")/.."
|
||||
export ENCELADO_CONFIG_DIR="$(pwd)/deploy/local/config"
|
||||
export ENCELADO_DATA_DIR="$(pwd)/deploy/local/data"
|
||||
export ENCELADO_WEB_PORT="${ENCELADO_WEB_PORT:-8080}"
|
||||
export ENCELADO_PASSWORD="sviluppo"
|
||||
mkdir -p "$ENCELADO_CONFIG_DIR" "$ENCELADO_DATA_DIR"
|
||||
|
||||
MODE="--no-autostart"
|
||||
@@ -21,5 +25,7 @@ for a in "$@"; do
|
||||
done
|
||||
|
||||
dotnet build src/Encelado.Server -c Debug -nologo -v q
|
||||
echo "Encelado in locale: http://localhost:$ENCELADO_WEB_PORT/ (config in deploy/local/config, dati in deploy/local/data)"
|
||||
WHERE="config in deploy/local/config, dati in deploy/local/data"
|
||||
[ "$MODE" = "--sample" ] && WHERE="campione: cartelle temporanee, deploy/local non viene letto"
|
||||
echo "Encelado in locale: http://localhost:$ENCELADO_WEB_PORT/ password: quella della sandbox, sviluppo (solo localhost; $WHERE)"
|
||||
exec dotnet src/Encelado.Server/bin/Debug/net10.0/Encelado.Server.dll $MODE
|
||||
@@ -4,10 +4,10 @@
|
||||
|
||||
.DESCRIPTION
|
||||
Le cartelle deploy/local/config e deploy/local/data vengono montate come /config e /data:
|
||||
sono le stesse di scripts\run-dev.ps1, quindi configurazione e chiavi salvate valgono
|
||||
in entrambi i modi. Il token dell'interfaccia è "sviluppo" salvo ENCELADO_WEB_TOKEN in
|
||||
un file .env accanto alla compose (dove vanno anche ETORO_API_KEY, ETORO_USER_KEY,
|
||||
TELEGRAM_*). Segue il log finché non premi Ctrl+C; il container resta acceso:
|
||||
sono le stesse di scripts\run-dev.ps1, quindi configurazione e segreti salvati valgono
|
||||
in entrambi i modi. La password dell'interfaccia è "sviluppo" salvo ENCELADO_PASSWORD in
|
||||
un file .env accanto alla compose; conto, chiavi eToro e Telegram si impostano dalla
|
||||
pagina Impostazioni. Segue il log finché non premi Ctrl+C; il container resta acceso:
|
||||
scripts\run-docker.ps1 -Down per fermarlo (SIGTERM, stop pulito).
|
||||
|
||||
scripts\run-docker.ps1 # build + up -d + log
|
||||
@@ -27,14 +27,17 @@ if ($Down) { docker compose down; exit $LASTEXITCODE }
|
||||
|
||||
New-Item -ItemType Directory -Force "deploy\local\config", "deploy\local\data" | Out-Null
|
||||
$env:GIT_COMMIT = (git rev-parse --short=12 HEAD 2>$null); if (-not $env:GIT_COMMIT) { $env:GIT_COMMIT = "n/d" }
|
||||
$env:PUID = "1000"; $env:PGID = "1000"
|
||||
|
||||
if ($NoBuild) { docker compose up -d } else { docker compose up -d --build }
|
||||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||||
|
||||
$port = if ($env:ENCELADO_WEB_PORT) { $env:ENCELADO_WEB_PORT } else { "8080" }
|
||||
$token = if ($env:ENCELADO_WEB_TOKEN) { "(da ENCELADO_WEB_TOKEN)" } else { "sviluppo" }
|
||||
# Da dove viene la password, mai il suo valore (può essere una vera): la variabile, poi il .env della compose.
|
||||
$envFile = Join-Path $root ".env"
|
||||
$password = if ($env:ENCELADO_PASSWORD) { "(da ENCELADO_PASSWORD)" }
|
||||
elseif ((Test-Path $envFile) -and (Select-String -Path $envFile -Pattern '^\s*ENCELADO_PASSWORD=.+' -Quiet)) { "(da .env)" }
|
||||
else { "sviluppo (quella predefinita della compose)" }
|
||||
$url = "http://localhost:$port/"
|
||||
Write-Host "Encelado nel container: $url token: $token (docker compose down per fermare)" -ForegroundColor Cyan
|
||||
Write-Host "Encelado nel container: $url password: $password (docker compose down per fermare)" -ForegroundColor Cyan
|
||||
if (-not $NoBrowser) { Start-Job -ScriptBlock { param($u) Start-Sleep -Seconds 4; Start-Process $u } -ArgumentList $url | Out-Null }
|
||||
docker compose logs -f encelado
|
||||
@@ -1,7 +1,8 @@
|
||||
#!/usr/bin/env sh
|
||||
# Builds the image and starts Encelado in the container with the docker-compose.yml at the root.
|
||||
# deploy/local/config and deploy/local/data are mounted as /config and /data (the same
|
||||
# folders scripts/run-dev.sh uses). Token "sviluppo" unless ENCELADO_WEB_TOKEN is in .env.
|
||||
# folders scripts/run-dev.sh uses). Interface password "sviluppo" unless ENCELADO_PASSWORD
|
||||
# is in .env; account, eToro keys and Telegram are set from the Impostazioni page.
|
||||
# sh scripts/run-docker.sh # build + up -d + follow the log (Ctrl+C leaves it running)
|
||||
# sh scripts/run-docker.sh --no-build
|
||||
# sh scripts/run-docker.sh --down # docker compose down (SIGTERM, clean stop)
|
||||
@@ -12,7 +13,14 @@ case "${1:-}" in
|
||||
esac
|
||||
mkdir -p deploy/local/config deploy/local/data
|
||||
export GIT_COMMIT="$(git rev-parse --short=12 HEAD 2>/dev/null || echo n/d)"
|
||||
export PUID="${PUID:-1000}" PGID="${PGID:-1000}"
|
||||
if [ "${1:-}" = "--no-build" ]; then docker compose up -d; else docker compose up -d --build; fi
|
||||
echo "Encelado nel container: http://localhost:${ENCELADO_WEB_PORT:-8080}/ token: ${ENCELADO_WEB_TOKEN:-sviluppo} (sh scripts/run-docker.sh --down per fermare)"
|
||||
# Where the password comes from, never its value (it may be a real one).
|
||||
if [ -n "${ENCELADO_PASSWORD:-}" ]; then
|
||||
PASSWORD_NOTE="(da ENCELADO_PASSWORD)"
|
||||
elif [ -f .env ] && grep -Eq '^[[:space:]]*ENCELADO_PASSWORD=.+' .env; then
|
||||
PASSWORD_NOTE="(da .env)"
|
||||
else
|
||||
PASSWORD_NOTE="sviluppo (quella predefinita della compose)"
|
||||
fi
|
||||
echo "Encelado nel container: http://localhost:${ENCELADO_WEB_PORT:-8080}/ password: $PASSWORD_NOTE (sh scripts/run-docker.sh --down per fermare)"
|
||||
exec docker compose logs -f encelado
|
||||
@@ -1,47 +1,134 @@
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Rigenera docs/img/*.png: server in modalità campione (--sample) e Edge headless su ogni pagina.
|
||||
Rigenera docs/img/*.png: il server in modalità campione (--sample) e Edge headless su ogni pagina.
|
||||
|
||||
.DESCRIPTION
|
||||
Niente chiavi, niente mercato: lo snapshot è finto (SampleSnapshot). Serve Microsoft Edge.
|
||||
La pagina viene aperta con ?once=1 (una sola lettura dello snapshot, nessuno stream), altrimenti
|
||||
il browser headless non considera mai il caricamento concluso.
|
||||
Niente chiavi, niente mercato: i dati sono d'esempio ma coerenti fra loro (SampleData), su una
|
||||
configurazione temporanea che non tocca la sandbox né Documenti. Serve Microsoft Edge.
|
||||
|
||||
scripts\screenshots.ps1 [-Port 58085]
|
||||
Le pagine si aprono con ?once=1 (una sola lettura dello snapshot, nessuno stream: con uno stream
|
||||
aperto il browser headless non considera mai concluso il caricamento). Le foto da computer
|
||||
(1440x900) usano --screenshot; quella da telefono (420x860) passa dal protocollo DevTools con
|
||||
l'emulazione della finestra, perché Edge per desktop non stringe la finestra sotto circa 500 px
|
||||
e --window-size=420 darebbe una pagina larga 500 tagliata a destra.
|
||||
|
||||
scripts\screenshots.ps1 [-Port 58085] [-Only dashboard,mobile]
|
||||
#>
|
||||
param([int] $Port = 58085)
|
||||
param([int] $Port = 58085, [string[]] $Only = @())
|
||||
$ErrorActionPreference = "Stop"
|
||||
$root = Split-Path -Parent $PSScriptRoot
|
||||
Set-Location $root
|
||||
$edge = @("$env:ProgramFiles (x86)\Microsoft\Edge\Application\msedge.exe", "$env:ProgramFiles\Microsoft\Edge\Application\msedge.exe") | Where-Object { Test-Path $_ } | Select-Object -First 1
|
||||
$edge = @("${env:ProgramFiles(x86)}\Microsoft\Edge\Application\msedge.exe", "$env:ProgramFiles\Microsoft\Edge\Application\msedge.exe") | Where-Object { Test-Path $_ } | Select-Object -First 1
|
||||
if (-not $edge) { throw "Microsoft Edge non trovato" }
|
||||
|
||||
# Pagina, nome del file e dimensione; "mobile" è la dashboard su un telefono.
|
||||
$shots = @(
|
||||
@{ name = "dashboard"; page = "dashboard"; size = "1440,900" },
|
||||
@{ name = "dashboard-chiaro"; page = "dashboard"; size = "1440,900"; query = "theme=light" },
|
||||
@{ name = "basket"; page = "basket"; size = "1440,900" },
|
||||
@{ name = "posizioni"; page = "posizioni"; size = "1440,900" },
|
||||
@{ name = "mercato"; page = "mercato"; size = "1440,900" },
|
||||
@{ name = "storico"; page = "storico"; size = "1440,900" },
|
||||
@{ name = "apprendimento"; page = "apprendimento"; size = "1440,900" },
|
||||
@{ name = "log"; page = "log"; size = "1440,900" },
|
||||
@{ name = "sistema"; page = "sistema"; size = "1440,900" },
|
||||
@{ name = "impostazioni"; page = "impostazioni"; size = "1440,900" },
|
||||
@{ name = "login"; page = "login"; size = "1440,900" },
|
||||
@{ name = "mobile"; page = "dashboard"; size = "420,860"; device = $true }
|
||||
)
|
||||
if ($Only.Count -gt 0) { $shots = @($shots | Where-Object { $Only -contains $_.name }) }
|
||||
|
||||
function Get-PageUrl($shot) {
|
||||
if ($shot.page -eq "login") { return "http://127.0.0.1:$Port/login" }
|
||||
$q = "once=1" + $(if ($shot.query) { "&" + $shot.query } else { "" })
|
||||
return "http://127.0.0.1:$Port/?$q#/$($shot.page)"
|
||||
}
|
||||
|
||||
# One DevTools command over the page's WebSocket; events that arrive meanwhile are skipped.
|
||||
function Invoke-Cdp($ws, [int] $id, [string] $method, $params) {
|
||||
$json = @{ id = $id; method = $method; params = $params } | ConvertTo-Json -Depth 6 -Compress
|
||||
$bytes = [Text.Encoding]::UTF8.GetBytes($json)
|
||||
$ws.SendAsync([ArraySegment[byte]]::new($bytes), [Net.WebSockets.WebSocketMessageType]::Text, $true, [Threading.CancellationToken]::None).Wait()
|
||||
$buffer = New-Object byte[] 65536
|
||||
while ($true) {
|
||||
$ms = New-Object IO.MemoryStream
|
||||
do {
|
||||
$r = $ws.ReceiveAsync([ArraySegment[byte]]::new($buffer), [Threading.CancellationToken]::None).Result
|
||||
$ms.Write($buffer, 0, $r.Count)
|
||||
} while (-not $r.EndOfMessage)
|
||||
$text = [Text.Encoding]::UTF8.GetString($ms.ToArray())
|
||||
if ($text -match ('^\{"id":' + $id + '[,}]')) { return $text }
|
||||
}
|
||||
}
|
||||
|
||||
# The phone shot: a real 420 px viewport through the DevTools protocol (no Node, no library).
|
||||
function Save-DeviceShot([string] $url, [string] $out, [int] $width, [int] $height, [string] $profileDir) {
|
||||
$debugPort = Get-Random -Minimum 9300 -Maximum 9800
|
||||
$edgeArgs = @("--headless=new", "--disable-gpu", "--no-first-run", "--no-default-browser-check", "--hide-scrollbars", "--disable-extensions", "--remote-debugging-port=$debugPort", "--user-data-dir=$profileDir", "about:blank")
|
||||
$browser = Start-Process -FilePath $edge -ArgumentList $edgeArgs -PassThru -WindowStyle Hidden -RedirectStandardError "$profileDir.err" -RedirectStandardOutput "$profileDir.out"
|
||||
$ws = $null
|
||||
try {
|
||||
$target = $null
|
||||
for ($i = 0; $i -lt 60 -and -not $target; $i++) {
|
||||
Start-Sleep -Milliseconds 250
|
||||
# PowerShell 5.1 passes a JSON array down the pipeline as one object: @() enumerates it.
|
||||
try { $list = (Invoke-WebRequest -UseBasicParsing "http://127.0.0.1:$debugPort/json/list" -TimeoutSec 2).Content | ConvertFrom-Json; $target = @($list) | Where-Object { $_.type -eq "page" } | Select-Object -First 1 } catch {}
|
||||
}
|
||||
if (-not $target) { throw "Edge non espone il protocollo DevTools sulla porta $debugPort" }
|
||||
$ws = New-Object Net.WebSockets.ClientWebSocket
|
||||
$ws.ConnectAsync([Uri] $target.webSocketDebuggerUrl, [Threading.CancellationToken]::None).Wait()
|
||||
Invoke-Cdp $ws 1 "Emulation.setDeviceMetricsOverride" @{ width = $width; height = $height; deviceScaleFactor = 1; mobile = $true } | Out-Null
|
||||
Invoke-Cdp $ws 2 "Page.navigate" @{ url = $url } | Out-Null
|
||||
Start-Sleep -Seconds 4
|
||||
$answer = Invoke-Cdp $ws 3 "Page.captureScreenshot" @{ format = "png" }
|
||||
$data = [regex]::Match($answer, '"data":"([^"]+)"')
|
||||
if (-not $data.Success) { throw "screenshot non ricevuto: $($answer.Substring(0, [Math]::Min(200, $answer.Length)))" }
|
||||
[IO.File]::WriteAllBytes($out, [Convert]::FromBase64String($data.Groups[1].Value))
|
||||
}
|
||||
finally {
|
||||
if ($ws) { $ws.Dispose() }
|
||||
# The whole tree of this headless Edge (renderer, GPU, crashpad), never another Edge of the user.
|
||||
if (-not $browser.HasExited) { & taskkill.exe /PID $browser.Id /T /F 2>&1 | Out-Null }
|
||||
}
|
||||
}
|
||||
|
||||
dotnet build src/Encelado.Server -c Debug -nologo -v q
|
||||
if ($LASTEXITCODE -ne 0) { throw "compilazione non riuscita" }
|
||||
$work = Join-Path $env:TEMP ("encelado-shot-" + [guid]::NewGuid().ToString("N"))
|
||||
New-Item -ItemType Directory -Force "$work\config", "docs\img" | Out-Null
|
||||
New-Item -ItemType Directory -Force "$work\config", "$work\data", "docs\img" | Out-Null
|
||||
|
||||
# The sample server gets its own folders and no password (a password would show the login everywhere);
|
||||
# the variables of this session are put back at the end.
|
||||
$variables = "ENCELADO_CONFIG_DIR", "ENCELADO_DATA_DIR", "ENCELADO_PASSWORD", "ENCELADO_WEB_TOKEN"
|
||||
$saved = @{}
|
||||
foreach ($v in $variables) { $saved[$v] = [Environment]::GetEnvironmentVariable($v, "Process") }
|
||||
$env:ENCELADO_CONFIG_DIR = "$work\config"
|
||||
$server = Start-Process -FilePath "dotnet" -ArgumentList "src/Encelado.Server/bin/Debug/net10.0/Encelado.Server.dll", "--sample", "--port", "$Port" -PassThru -WindowStyle Hidden
|
||||
$env:ENCELADO_DATA_DIR = "$work\data"
|
||||
Remove-Item Env:ENCELADO_PASSWORD, Env:ENCELADO_WEB_TOKEN -ErrorAction SilentlyContinue
|
||||
$server = Start-Process -FilePath "dotnet" -ArgumentList "src/Encelado.Server/bin/Debug/net10.0/Encelado.Server.dll", "--sample", "--port", "$Port" -PassThru -WindowStyle Hidden -RedirectStandardOutput "$work\server.out" -RedirectStandardError "$work\server.err"
|
||||
try {
|
||||
$ready = $false
|
||||
for ($i = 0; $i -lt 30 -and -not $ready; $i++) { Start-Sleep -Seconds 1; try { $ready = (Invoke-WebRequest -UseBasicParsing "http://127.0.0.1:$Port/api/health" -TimeoutSec 2).StatusCode -eq 200 } catch {} }
|
||||
if (-not $ready) { throw "il server campione non risponde sulla porta $Port" }
|
||||
$shots = @(
|
||||
@{ name = "dashboard"; page = "dashboard"; size = "1440,900" },
|
||||
@{ name = "storico"; page = "storico"; size = "1440,900" },
|
||||
@{ name = "log"; page = "log"; size = "1440,900" },
|
||||
@{ name = "impostazioni"; page = "impostazioni"; size = "1440,900" },
|
||||
@{ name = "mobile"; page = "dashboard"; size = "420,860" }
|
||||
)
|
||||
foreach ($s in $shots) {
|
||||
$out = Join-Path $root ("docs\img\" + $s.name + ".png")
|
||||
$profile = Join-Path $work ("edge-" + $s.name)
|
||||
# Start-Process: Edge scrive avvisi su stderr e in PowerShell 5.1 diventerebbero errori bloccanti.
|
||||
$edgeArgs = @("--headless=new", "--disable-gpu", "--no-first-run", "--hide-scrollbars", "--user-data-dir=$profile", "--window-size=$($s.size)", "--virtual-time-budget=5000", "--screenshot=$out", "http://127.0.0.1:$Port/?once=1#/$($s.page)")
|
||||
Start-Process -FilePath $edge -ArgumentList $edgeArgs -Wait -NoNewWindow -RedirectStandardError "$profile.err" -RedirectStandardOutput "$profile.out"
|
||||
if (Test-Path $out) { Write-Host (" {0,-14} {1,7:N0} byte" -f $s.name, (Get-Item $out).Length) } else { Write-Warning "$($s.name): screenshot non scritto" }
|
||||
$profileDir = Join-Path $work ("edge-" + $s.name)
|
||||
if (Test-Path $out) { Remove-Item $out -Force }
|
||||
$w, $h = $s.size.Split(",")
|
||||
if ($s.device) {
|
||||
Save-DeviceShot (Get-PageUrl $s) $out ([int] $w) ([int] $h) $profileDir
|
||||
}
|
||||
else {
|
||||
# Start-Process: Edge scrive avvisi su stderr e in PowerShell 5.1 diventerebbero errori bloccanti.
|
||||
$edgeArgs = @("--headless=new", "--disable-gpu", "--no-first-run", "--no-default-browser-check", "--hide-scrollbars", "--disable-extensions", "--user-data-dir=$profileDir", "--window-size=$($s.size)", "--virtual-time-budget=6000", "--screenshot=$out", (Get-PageUrl $s))
|
||||
Start-Process -FilePath $edge -ArgumentList $edgeArgs -Wait -WindowStyle Hidden -RedirectStandardError "$profileDir.err" -RedirectStandardOutput "$profileDir.out"
|
||||
}
|
||||
if (Test-Path $out) { Write-Host (" {0,-17} {1,9:N0} byte" -f $s.name, (Get-Item $out).Length) } else { Write-Warning "$($s.name): screenshot non scritto" }
|
||||
}
|
||||
}
|
||||
finally {
|
||||
if ($server -and -not $server.HasExited) { Stop-Process -Id $server.Id -Force }
|
||||
foreach ($v in $variables) { [Environment]::SetEnvironmentVariable($v, $saved[$v], "Process") }
|
||||
Start-Sleep -Milliseconds 500
|
||||
Remove-Item $work -Recurse -Force -ErrorAction SilentlyContinue
|
||||
}
|
||||
@@ -1,7 +1,9 @@
|
||||
#!/usr/bin/env sh
|
||||
# Regenerates docs/img/*.png: the server in sample mode (--sample) and a headless Edge/Chrome on every page.
|
||||
# No keys, no market: the snapshot is fake. Pages are opened with ?once=1 (one snapshot, no stream),
|
||||
# otherwise the headless browser never considers the page loaded.
|
||||
# No keys, no market: the data is sample data, consistent across the pages. Pages are opened with ?once=1
|
||||
# (one snapshot, no stream), otherwise the headless browser never considers the page loaded. The phone
|
||||
# shot (420x860) needs a true 420 px viewport: through the DevTools protocol with Node 22+ when present
|
||||
# (scripts/cdp-shot.mjs), otherwise --window-size, which desktop Edge widens to about 500 px.
|
||||
# sh scripts/screenshots.sh [port]
|
||||
set -eu
|
||||
cd "$(dirname "$0")/.."
|
||||
@@ -13,20 +15,47 @@ for c in "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" "/c/Prog
|
||||
done
|
||||
[ -n "$BROWSER" ] || { echo "nessun browser Chromium trovato (imposta ENCELADO_BROWSER)" >&2; exit 1; }
|
||||
|
||||
# Windows paths for the native programs when running in Git Bash.
|
||||
native() { if command -v cygpath >/dev/null 2>&1; then cygpath -w "$1"; else printf '%s' "$1"; fi; }
|
||||
|
||||
dotnet build src/Encelado.Server -c Debug -nologo -v q
|
||||
WORK="$(mktemp -d)"
|
||||
trap '[ -n "${PID:-}" ] && kill "$PID" 2>/dev/null; rm -rf "$WORK"' EXIT
|
||||
mkdir -p "$WORK/config" docs/img
|
||||
ENCELADO_CONFIG_DIR="$WORK/config" dotnet src/Encelado.Server/bin/Debug/net10.0/Encelado.Server.dll --sample --port "$PORT" >/dev/null 2>&1 &
|
||||
cleanup() {
|
||||
if [ -n "${PID:-}" ]; then kill "$PID" 2>/dev/null || true; wait "$PID" 2>/dev/null || true; fi
|
||||
# On Windows the server's log file may stay locked for a moment after the process exits.
|
||||
rm -rf "$WORK" 2>/dev/null || { sleep 2; rm -rf "$WORK" 2>/dev/null || true; }
|
||||
}
|
||||
trap cleanup EXIT
|
||||
mkdir -p "$WORK/config" "$WORK/data" docs/img
|
||||
# Own folders and no password: a password would show the login page everywhere.
|
||||
env -u ENCELADO_PASSWORD -u ENCELADO_WEB_TOKEN ENCELADO_CONFIG_DIR="$WORK/config" ENCELADO_DATA_DIR="$WORK/data" \
|
||||
dotnet src/Encelado.Server/bin/Debug/net10.0/Encelado.Server.dll --sample --port "$PORT" >"$WORK/server.out" 2>&1 &
|
||||
PID=$!
|
||||
i=0; until curl -sf "http://127.0.0.1:$PORT/api/health" >/dev/null 2>&1; do i=$((i+1)); [ "$i" -lt 30 ] || { echo "il server campione non risponde" >&2; exit 1; }; sleep 1; done
|
||||
|
||||
shot() { # shot <name> <page> <size>
|
||||
"$BROWSER" --headless=new --disable-gpu --no-first-run --hide-scrollbars "--user-data-dir=$WORK/edge-$1" "--window-size=$3" --virtual-time-budget=5000 "--screenshot=$(pwd)/docs/img/$1.png" "http://127.0.0.1:$PORT/?once=1#/$2" >/dev/null 2>&1 || true
|
||||
[ -s "docs/img/$1.png" ] && echo " $1: $(wc -c < "docs/img/$1.png") byte" || echo " $1: screenshot non scritto" >&2
|
||||
report() { [ -s "docs/img/$1.png" ] && echo " $1: $(wc -c < "docs/img/$1.png") byte" || echo " $1: screenshot non scritto" >&2; }
|
||||
|
||||
shot() { # shot <name> <url> <size>
|
||||
rm -f "docs/img/$1.png"
|
||||
"$BROWSER" --headless=new --disable-gpu --no-first-run --no-default-browser-check --hide-scrollbars --disable-extensions "--user-data-dir=$WORK/edge-$1" "--window-size=$3" --virtual-time-budget=6000 "--screenshot=$(pwd)/docs/img/$1.png" "$2" >/dev/null 2>&1 || true
|
||||
report "$1"
|
||||
}
|
||||
shot dashboard dashboard 1440,900
|
||||
shot storico storico 1440,900
|
||||
shot log log 1440,900
|
||||
shot impostazioni impostazioni 1440,900
|
||||
shot mobile dashboard 420,860
|
||||
|
||||
device_shot() { # device_shot <name> <url> <width> <height>
|
||||
rm -f "docs/img/$1.png"
|
||||
if command -v node >/dev/null 2>&1; then
|
||||
node scripts/cdp-shot.mjs "$(native "$BROWSER")" "$2" "$(native "$(pwd)/docs/img/$1.png")" "$3" "$4" "$(native "$WORK/edge-$1")" || true
|
||||
report "$1"
|
||||
else
|
||||
echo " $1: node non trovato, foto con --window-size (la pagina risulta larga circa 500 px)" >&2
|
||||
shot "$1" "$2" "$3,$4"
|
||||
fi
|
||||
}
|
||||
|
||||
BASE="http://127.0.0.1:$PORT"
|
||||
for page in dashboard basket posizioni mercato storico apprendimento log sistema impostazioni; do
|
||||
shot "$page" "$BASE/?once=1#/$page" 1440,900
|
||||
done
|
||||
shot dashboard-chiaro "$BASE/?once=1&theme=light#/dashboard" 1440,900
|
||||
shot login "$BASE/login" 1440,900
|
||||
device_shot mobile "$BASE/?once=1#/dashboard" 420 860
|
||||
@@ -210,15 +210,19 @@ public sealed class BacktestBroker : IBroker
|
||||
{
|
||||
if (!_positions.Remove(positionId, out Position? p))
|
||||
{
|
||||
return Task.FromResult(new CloseOutcome(false, true, 0, 0, 0, _now, 0, "posizione inesistente"));
|
||||
return Task.FromResult(new CloseOutcome(false, true, 0, 0, 0, _now, double.NaN, "posizione inesistente") { PositionId = positionId });
|
||||
}
|
||||
|
||||
double exit = Exit(p, withSlippage: true);
|
||||
double pnl = PipMath.LegPnlUsd(p.Instrument.Symbol, p.IsBuy, p.Units, p.Open, exit, MidOf);
|
||||
pnl = (double.IsNaN(pnl) ? 0 : pnl) - p.Fees;
|
||||
_balance += pnl;
|
||||
pnl = double.IsNaN(pnl) ? 0 : pnl;
|
||||
double net = pnl - p.Fees;
|
||||
_balance += net;
|
||||
|
||||
// The history keeps eToro's meaning (profit before fees, fees apart); the close answer
|
||||
// carries the final net result of the position, fees included.
|
||||
_closed.Add(new ClosedTrade(p.Id, p.Instrument.Id, p.IsBuy, p.Units, p.Open, exit, p.OpenedUtc, _now, pnl, p.Fees));
|
||||
return Task.FromResult(new CloseOutcome(true, false, _nextId++, exit, p.Units, _now, pnl, string.Empty));
|
||||
return Task.FromResult(new CloseOutcome(true, false, _nextId++, exit, p.Units, _now, net, string.Empty) { PositionId = p.Id });
|
||||
}
|
||||
|
||||
public Task<bool> UpdateStopsAsync(long positionId, double? stopLoss, double? takeProfit, CancellationToken ct) => Task.FromResult(true);
|
||||
|
||||
@@ -93,6 +93,35 @@ public sealed record BacktestSettings
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The daily-loss block of the replay, bar by bar (D-52, the live engine's rule): the UTC day
|
||||
/// starts with the equity of its first bar; once the day's loss reaches <c>dailyLossPct</c> no
|
||||
/// entry and no add until the next day, even if the equity recovers in between.
|
||||
/// </summary>
|
||||
public sealed class ReplayDailyLoss
|
||||
{
|
||||
private readonly DailyLossLatch _latch = new();
|
||||
|
||||
/// <summary>The UTC day of the last bar.</summary>
|
||||
public DateOnly Day { get; private set; }
|
||||
|
||||
/// <summary>The equity of the day's first bar; NaN before the first bar.</summary>
|
||||
public double DayStartEquity { get; private set; } = double.NaN;
|
||||
|
||||
/// <summary>The bar at <paramref name="barUtc"/> with the equity <paramref name="equityNow"/>: true while the day's block holds.</summary>
|
||||
public bool Blocked(DateTime barUtc, double equityNow, double dailyLossPct)
|
||||
{
|
||||
DateOnly day = DateOnly.FromDateTime(barUtc);
|
||||
if (day != Day)
|
||||
{
|
||||
Day = day;
|
||||
DayStartEquity = equityNow;
|
||||
}
|
||||
|
||||
return _latch.Evaluate(Day, DayStartEquity, equityNow, dailyLossPct);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>One basket, opened and closed, as the backtest saw it.</summary>
|
||||
public sealed record BacktestTrade(
|
||||
string Basket,
|
||||
@@ -166,7 +195,7 @@ public sealed record BacktestResult(
|
||||
/// What the replay cannot do, and says so: the economic-calendar blackout and the
|
||||
/// sentiment features need history the free feeds do not provide, so in the backtest
|
||||
/// they are absent (no blackout applied). The live bot applies them; the comparison
|
||||
/// backtest → paper → forward is where their effect shows.
|
||||
/// backtest → demo account → forward is where their effect shows.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public static class BasketBacktest
|
||||
@@ -216,7 +245,7 @@ public static class BasketBacktest
|
||||
int equityStops = 0;
|
||||
List<(DateOnly Day, double Equity)> daily = [];
|
||||
DateOnly currentDay = default;
|
||||
double dayStartEquity = settings.StartingBalance;
|
||||
ReplayDailyLoss dailyLossBlock = new();
|
||||
double peak = settings.StartingBalance;
|
||||
double lastEquity = settings.StartingBalance;
|
||||
int bars = 0;
|
||||
@@ -311,10 +340,11 @@ public static class BasketBacktest
|
||||
}
|
||||
|
||||
currentDay = day;
|
||||
dayStartEquity = equityNow;
|
||||
}
|
||||
|
||||
bool dailyLoss = dayStartEquity > 0 && (dayStartEquity - equityNow) / dayStartEquity >= config.DailyLossPct / 100.0;
|
||||
// The same rule and the same block as the live engine (D-52): once hit, nothing new until
|
||||
// 00:00 UTC, even if the equity recovers. The replay has no cash movements, so its equity is net equity.
|
||||
bool dailyLoss = dailyLossBlock.Blocked(t, equityNow, config.DailyLossPct);
|
||||
|
||||
foreach (Slot slot in slots)
|
||||
{
|
||||
|
||||
@@ -90,72 +90,7 @@ public static class BasketTrials
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(c);
|
||||
BasketStrategyConfig copy = BasketStrategyConfig.ParseText(BasketStrategyConfig.DefaultJson, out _);
|
||||
copy.Risk = new RiskOptions
|
||||
{
|
||||
MaxMarginUsePct = c.Risk.MaxMarginUsePct,
|
||||
MaxMarginPerBasketPct = c.Risk.MaxMarginPerBasketPct,
|
||||
MarginBufferPct = c.Risk.MarginBufferPct,
|
||||
CloseForeignOnKill = c.Risk.CloseForeignOnKill,
|
||||
MarginCallBlockRatio = c.Risk.MarginCallBlockRatio,
|
||||
MarginCallCloseRatio = c.Risk.MarginCallCloseRatio,
|
||||
};
|
||||
copy.Recovery = new RecoveryOptions { ThresholdMinutes = c.Recovery.ThresholdMinutes, WarmupMinutes = c.Recovery.WarmupMinutes, HeartbeatSeconds = c.Recovery.HeartbeatSeconds };
|
||||
copy.Learning = new LearningOptions { Enabled = c.Learning.Enabled, WeeklyCycle = c.Learning.WeeklyCycle, Challenger = c.Learning.Challenger };
|
||||
copy.Preset = c.Preset;
|
||||
copy.SignalMode = c.SignalMode;
|
||||
copy.ExitMode = c.ExitMode;
|
||||
copy.AveragingMode = c.AveragingMode;
|
||||
copy.TpMode = c.TpMode;
|
||||
copy.SameCrossPolicy = c.SameCrossPolicy;
|
||||
copy.PreferDirectCross = c.PreferDirectCross;
|
||||
copy.InvertSignal = c.InvertSignal;
|
||||
copy.Window = c.Window;
|
||||
copy.WindowShort = c.WindowShort;
|
||||
copy.RhoMin = c.RhoMin;
|
||||
copy.RhoShortMin = c.RhoShortMin;
|
||||
copy.HalfLifeMinBars = c.HalfLifeMinBars;
|
||||
copy.HalfLifeMaxBars = c.HalfLifeMaxBars;
|
||||
copy.HalfLifeRecalcHours = c.HalfLifeRecalcHours;
|
||||
copy.AtrPeriod = c.AtrPeriod;
|
||||
copy.EwmaSpan = c.EwmaSpan;
|
||||
copy.TrendPeriod = c.TrendPeriod;
|
||||
copy.ZOut = c.ZOut;
|
||||
copy.DIn = c.DIn;
|
||||
copy.AnchorBars = c.AnchorBars;
|
||||
copy.GridStepZ = c.GridStepZ;
|
||||
copy.LotMultiplier = c.LotMultiplier;
|
||||
copy.MaxLossPerBasketPct = c.MaxLossPerBasketPct;
|
||||
copy.RhoBreak = c.RhoBreak;
|
||||
copy.RhoBreakBars = c.RhoBreakBars;
|
||||
copy.MaxHoldingBars = c.MaxHoldingBars;
|
||||
copy.TpAtrMultiple = c.TpAtrMultiple;
|
||||
copy.CostMultiple = c.CostMultiple;
|
||||
copy.SpreadMedianMultiple = c.SpreadMedianMultiple;
|
||||
copy.SpreadAnomalyMultiple = c.SpreadAnomalyMultiple;
|
||||
copy.SlippagePipsPerLeg = c.SlippagePipsPerLeg;
|
||||
copy.OvernightPipsPerDay = c.OvernightPipsPerDay;
|
||||
copy.BlackoutBeforeMin = c.BlackoutBeforeMin;
|
||||
copy.BlackoutAfterMin = c.BlackoutAfterMin;
|
||||
copy.FridayCutoffUtcHour = c.FridayCutoffUtcHour;
|
||||
copy.OpenDelayMinutes = c.OpenDelayMinutes;
|
||||
copy.Sessions = [.. c.Sessions];
|
||||
copy.MaxEffectiveLeverage = c.MaxEffectiveLeverage;
|
||||
copy.OrderLeverage = c.OrderLeverage;
|
||||
copy.VolScaleMin = c.VolScaleMin;
|
||||
copy.VolScaleMax = c.VolScaleMax;
|
||||
copy.VolAverageDays = c.VolAverageDays;
|
||||
copy.MlMinProbability = c.MlMinProbability;
|
||||
copy.EquityStopPct = c.EquityStopPct;
|
||||
copy.DailyLossPct = c.DailyLossPct;
|
||||
copy.LegTimeoutSec = c.LegTimeoutSec;
|
||||
copy.ClockSkewMaxSeconds = c.ClockSkewMaxSeconds;
|
||||
copy.ZInOverride = c.ZInOverride;
|
||||
copy.RiskPerBasketPctOverride = c.RiskPerBasketPctOverride;
|
||||
copy.MaxBasketsOverride = c.MaxBasketsOverride;
|
||||
copy.TpPipsOverride = c.TpPipsOverride;
|
||||
copy.MaxAddsOverride = c.MaxAddsOverride;
|
||||
copy.ZStopOverride = c.ZStopOverride;
|
||||
copy.Baskets = [.. c.Baskets.Select(static b => new BasketDefinition { A = b.A, B = b.B, Enabled = b.Enabled, Note = b.Note })];
|
||||
copy.CopyFrom(c);
|
||||
return copy;
|
||||
}
|
||||
|
||||
|
||||
@@ -211,8 +211,24 @@ public sealed class BasketDecider
|
||||
|
||||
public BasketPreset Preset => _preset;
|
||||
|
||||
/// <summary>Hot swap of the preset: open baskets keep the numbers they were opened with.</summary>
|
||||
public void SetPreset(PresetName name) => _preset = _cfg.Effective(name);
|
||||
/// <summary>
|
||||
/// Takes the configuration again after it changed in place (a save in Impostazioni,
|
||||
/// applied on the decision thread): the preset in force is recomputed from the file's
|
||||
/// preset and overrides and the cached half-lives are recomputed at the next bar (the
|
||||
/// window may have changed). The PipDivergence anchors are dropped only when asked —
|
||||
/// when the signal mode or the anchor period changed —, since a new anchor moves the
|
||||
/// signal. Open baskets keep the z stop, the adds, the take-profit and the maximum loss
|
||||
/// they entered with (they travel in the <see cref="BasketPosition"/>).
|
||||
/// </summary>
|
||||
public void Reload(bool resetAnchors = false)
|
||||
{
|
||||
_preset = _cfg.Effective();
|
||||
_halfLives.Clear();
|
||||
if (resetAnchors)
|
||||
{
|
||||
_anchors.Clear();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Bars of the timeframe in one day (M15 → 96).</summary>
|
||||
public const int BarsPerDay = 96;
|
||||
@@ -451,7 +467,7 @@ public sealed class BasketDecider
|
||||
{
|
||||
"kill_switch" => "kill-switch attivo: nessuna nuova entrata",
|
||||
"equity_stop" => "equity stop attivo: serve un reset manuale",
|
||||
"daily_loss" => "perdita giornaliera massima raggiunta: niente entrate fino a domani",
|
||||
"daily_loss" => "perdita giornaliera massima raggiunta: niente nuove entrate fino alle 00:00 UTC, anche se l'equity recupera",
|
||||
"entries_blocked" => $"entrate bloccate: {ctx.EntriesBlockedReason}",
|
||||
_ => $"qualità dati: {ctx.A.QualityIssue ?? ctx.B.QualityIssue}",
|
||||
};
|
||||
@@ -714,9 +730,11 @@ public sealed class BasketDecider
|
||||
}
|
||||
|
||||
// z stop can be judged on any quote too; correlation and time only on bar close.
|
||||
if (double.IsFinite(e.Z) && (p.BuyCross ? e.Z <= -_preset.ZStop : e.Z >= _preset.ZStop))
|
||||
// The stop is the one the basket entered with: a preset changed since then does not move it.
|
||||
double zStop = double.IsFinite(p.ZStop) && p.ZStop > 0 ? p.ZStop : _preset.ZStop;
|
||||
if (double.IsFinite(e.Z) && (p.BuyCross ? e.Z <= -zStop : e.Z >= zStop))
|
||||
{
|
||||
return Exit(e, ["stop_z"], F($"stop di basket: z {e.Z:+0.00;-0.00} oltre ±{_preset.ZStop:0.00} ({e.PipsOpen:+0.0;-0.0} pip, netto {Fmt2(e.PnlOpenUsd)} USD)"));
|
||||
return Exit(e, ["stop_z"], F($"stop di basket: z {e.Z:+0.00;-0.00} oltre ±{zStop:0.00} ({e.PipsOpen:+0.0;-0.0} pip, netto {Fmt2(e.PnlOpenUsd)} USD)"));
|
||||
}
|
||||
|
||||
if (!ctx.IsBarClose)
|
||||
@@ -742,16 +760,18 @@ public sealed class BasketDecider
|
||||
p.BarsWithBrokenCorrelation = 0;
|
||||
}
|
||||
|
||||
// Averaging (§5.5): only when |z| grew by GridStepZ since the last entry, within MaxAdds.
|
||||
// Averaging (§5.5): only when |z| grew by GridStepZ since the last entry, within the
|
||||
// adds the basket entered with.
|
||||
int presetAdds = p.MaxAdds >= 0 ? p.MaxAdds : _preset.MaxAdds;
|
||||
int maxAdds = _cfg.AveragingMode switch
|
||||
{
|
||||
AveragingMode.Off => 0,
|
||||
AveragingMode.AddOnce => Math.Min(1, _preset.MaxAdds),
|
||||
_ => _preset.MaxAdds,
|
||||
AveragingMode.AddOnce => Math.Min(1, presetAdds),
|
||||
_ => presetAdds,
|
||||
};
|
||||
|
||||
if (maxAdds > 0 && p.Adds < maxAdds && double.IsFinite(e.Z) &&
|
||||
Math.Abs(e.Z) - Math.Abs(p.LastAddZ) >= _cfg.GridStepZ && Math.Abs(e.Z) < _preset.ZStop &&
|
||||
Math.Abs(e.Z) - Math.Abs(p.LastAddZ) >= _cfg.GridStepZ && Math.Abs(e.Z) < zStop &&
|
||||
ctx.EntriesBlockedReason is null && !ctx.DailyLossHit)
|
||||
{
|
||||
double scale = Math.Pow(_cfg.LotMultiplier, p.Adds + 1);
|
||||
|
||||
@@ -30,9 +30,20 @@ public sealed record EntryOutcome(
|
||||
public TrackedOrder? PendingOrder { get; init; }
|
||||
|
||||
public bool IsPending => PendingLeg != PendingLeg.None;
|
||||
|
||||
/// <summary>When a leg was undone (<c>leg_risk_unwind</c>): the close of that leg, whose realised result is settled like any other.</summary>
|
||||
public CloseOutcome? UnwindClose { get; init; }
|
||||
|
||||
/// <summary>The leg that was undone, as it was filled.</summary>
|
||||
public BasketLeg? UnwoundLeg { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>What closing a basket produced.</summary>
|
||||
/// <summary>
|
||||
/// What closing a basket produced. <see cref="RealizedPnlUsd"/> is the venue's final number
|
||||
/// when every close carried one (<see cref="PnlFinal"/>, the simulators), otherwise the
|
||||
/// estimate from the exit prices (entry fees and accrued overnight subtracted) that the
|
||||
/// venue's history settles later; NaN when not even the estimate is possible.
|
||||
/// </summary>
|
||||
public sealed record ExitOutcome(
|
||||
bool Ok,
|
||||
double ExitPriceA,
|
||||
@@ -43,7 +54,14 @@ public sealed record ExitOutcome(
|
||||
double SlippagePipsB,
|
||||
string Error,
|
||||
DateTime ClosedUtc,
|
||||
IReadOnlyList<long> StuckPositionIds);
|
||||
IReadOnlyList<long> StuckPositionIds)
|
||||
{
|
||||
/// <summary>True when every close carried a final result (simulators); false: <see cref="RealizedPnlUsd"/> is an estimate to settle on the venue's history.</summary>
|
||||
public bool PnlFinal { get; init; }
|
||||
|
||||
/// <summary>Every close that went through, each with its position id.</summary>
|
||||
public IReadOnlyList<CloseOutcome> Closes { get; init; } = [];
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The two-leg execution protocol of §5.7, over any <see cref="IBroker"/>, with the
|
||||
@@ -107,6 +125,9 @@ public sealed class BasketExecutor
|
||||
UnitsB = sizing.UnitsB,
|
||||
TpPips = _cfg.TpMode == TpMode.AtrMultiple && double.IsFinite(decision.Evaluation.AtrPipsA) ? Math.Max(1, _cfg.TpAtrMultiple * decision.Evaluation.AtrPipsA) : preset.TpPips,
|
||||
MaxLossUsd = ctx.Equity * _cfg.MaxLossPerBasketPct / 100.0,
|
||||
ZStop = preset.ZStop,
|
||||
MaxAdds = preset.MaxAdds,
|
||||
Preset = preset.Label,
|
||||
EntryCostPips = decision.Cost?.CostPips ?? double.NaN,
|
||||
EquityAtEntry = ctx.Equity,
|
||||
Motivazione = decision.Motivazione,
|
||||
@@ -237,7 +258,11 @@ public sealed class BasketExecutor
|
||||
{
|
||||
CloseOutcome undo = await CloseLegAsync(legA.PositionId, legA.InstrumentId, TrackClose(legA, ctx.Name, plan.BasketId, OrderLeg.Unwind, "leg_risk_unwind: " + why), ct).ConfigureAwait(false);
|
||||
string error = $"{why}; gamba A {(undo.Closed ? "richiusa" : "NON richiusa: " + undo.Error)}";
|
||||
return new EntryOutcome(false, null, undo.Closed, error, SlipPips(ctx.A, legA.IsBuy, plan.QuoteA, legA.EntryPrice), 0, Environment.TickCount64 - t0);
|
||||
return new EntryOutcome(false, null, undo.Closed, error, SlipPips(ctx.A, legA.IsBuy, plan.QuoteA, legA.EntryPrice), 0, Environment.TickCount64 - t0)
|
||||
{
|
||||
UnwindClose = undo,
|
||||
UnwoundLeg = legA,
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>Closes a lone leg (a pending A whose signal decayed, an orphan): three attempts, verified on the position list.</summary>
|
||||
@@ -264,6 +289,7 @@ public sealed class BasketExecutor
|
||||
SentUtc = DateTime.UtcNow,
|
||||
Mode = _mode,
|
||||
Motivazione = reason,
|
||||
PositionId = position.PositionId,
|
||||
};
|
||||
return CloseLegAsync(position.PositionId, position.InstrumentId, track, ct);
|
||||
}
|
||||
@@ -284,6 +310,9 @@ public sealed class BasketExecutor
|
||||
EntryCostPips = plan.EntryCostPips,
|
||||
TpPips = plan.TpPips,
|
||||
MaxLossUsd = plan.MaxLossUsd,
|
||||
ZStop = plan.ZStop,
|
||||
MaxAdds = plan.MaxAdds,
|
||||
Preset = plan.Preset,
|
||||
EquityAtEntry = plan.EquityAtEntry,
|
||||
EntryMotivazione = plan.Motivazione,
|
||||
};
|
||||
@@ -347,9 +376,26 @@ public sealed class BasketExecutor
|
||||
SentUtc = DateTime.UtcNow,
|
||||
Mode = _mode,
|
||||
Motivazione = "leg_risk_unwind dell'aggiunta",
|
||||
PositionId = a.PositionId,
|
||||
};
|
||||
CloseOutcome undo = await CloseLegAsync(a.PositionId, ctx.A.Instrument.Id, undoTrack, ct).ConfigureAwait(false);
|
||||
return new EntryOutcome(false, p, undo.Closed, $"aggiunta su B non eseguita: {Describe(b)}", 0, 0, Environment.TickCount64 - t0);
|
||||
BasketLeg added = new()
|
||||
{
|
||||
Symbol = ctx.A.Symbol,
|
||||
InstrumentId = ctx.A.Instrument.Id,
|
||||
IsBuy = p.A.IsBuy,
|
||||
Units = a.Units > 0 ? a.Units : sizing.UnitsA,
|
||||
EntryPrice = a.FillRate > 0 ? a.FillRate : quoteA,
|
||||
PositionId = a.PositionId,
|
||||
ClientRef = reqA.ClientRef,
|
||||
OpenedUtc = a.TimeUtc == default ? DateTime.UtcNow : a.TimeUtc,
|
||||
EntryFeesUsd = a.Fees,
|
||||
};
|
||||
return new EntryOutcome(false, p, undo.Closed, $"aggiunta su B non eseguita: {Describe(b)}", 0, 0, Environment.TickCount64 - t0)
|
||||
{
|
||||
UnwindClose = undo,
|
||||
UnwoundLeg = added,
|
||||
};
|
||||
}
|
||||
|
||||
Merge(p.A, a, sizing.UnitsA, quoteA, reqA.ClientRef);
|
||||
@@ -378,26 +424,36 @@ public sealed class BasketExecutor
|
||||
double quoteA = p.A.IsBuy ? ctx.A.Quote.Bid : ctx.A.Quote.Ask;
|
||||
double quoteB = p.B.IsBuy ? ctx.B.Quote.Bid : ctx.B.Quote.Ask;
|
||||
List<long> stuck = [];
|
||||
List<CloseOutcome> closes = [];
|
||||
DateTime closedUtc = DateTime.UtcNow;
|
||||
|
||||
(double priceA, double pnlA, bool okA) = await CloseLegAllAsync(p.A, ctx.A.Instrument.Id, ctx.Name, p.BasketId, reason, stuck, ct).ConfigureAwait(false);
|
||||
(double priceB, double pnlB, bool okB) = await CloseLegAllAsync(p.B, ctx.B.Instrument.Id, ctx.Name, p.BasketId, reason, stuck, ct).ConfigureAwait(false);
|
||||
(double priceA, double pnlA, bool okA) = await CloseLegAllAsync(p.A, ctx.A.Instrument.Id, ctx.Name, p.BasketId, reason, stuck, closes, ct).ConfigureAwait(false);
|
||||
(double priceB, double pnlB, bool okB) = await CloseLegAllAsync(p.B, ctx.B.Instrument.Id, ctx.Name, p.BasketId, reason, stuck, closes, ct).ConfigureAwait(false);
|
||||
|
||||
double exitA = priceA > 0 ? priceA : quoteA;
|
||||
double exitB = priceB > 0 ? priceB : quoteB;
|
||||
|
||||
// Realised P&L: the venue's number when it reports one, our own otherwise.
|
||||
double own = p.NetPnlUsd(exitA, exitB, _mid);
|
||||
double pnl = okA && okB && (pnlA != 0 || pnlB != 0) ? pnlA + pnlB - p.AccruedFeesUsd : (double.IsNaN(own) ? 0 : own);
|
||||
// Realised P&L. A simulator gives the final net result of every position (its fees
|
||||
// included): that is the number, and nothing is subtracted again. eToro gives none
|
||||
// (NaN): the number here is the estimate from the exit prices — entry fees and
|
||||
// accrued overnight already subtracted — and the trade history settles it later.
|
||||
// NaN stays NaN: an unknown result is never read as zero.
|
||||
double estimate = p.NetPnlUsd(exitA, exitB, _mid);
|
||||
bool final = okA && okB && double.IsFinite(pnlA) && double.IsFinite(pnlB);
|
||||
double pnl = final ? pnlA + pnlB : estimate;
|
||||
double pips = p.PipsTotal(exitA, exitB, ctx.A.Instrument.Pip, ctx.B.Instrument.Pip);
|
||||
|
||||
bool ok = okA && okB;
|
||||
return new ExitOutcome(ok, exitA, exitB, pnl, pips,
|
||||
SlipPips(ctx.A, !p.A.IsBuy, quoteA, exitA), SlipPips(ctx.B, !p.B.IsBuy, quoteB, exitB),
|
||||
ok ? string.Empty : $"gambe non chiuse: {string.Join(", ", stuck)}", closedUtc, stuck);
|
||||
ok ? string.Empty : $"gambe non chiuse: {string.Join(", ", stuck)}", closedUtc, stuck)
|
||||
{
|
||||
PnlFinal = final,
|
||||
Closes = closes,
|
||||
};
|
||||
}
|
||||
|
||||
private async Task<(double Price, double Pnl, bool Ok)> CloseLegAllAsync(BasketLeg leg, long instrumentId, string basket, string basketId, string reason, List<long> stuck, CancellationToken ct)
|
||||
private async Task<(double Price, double Pnl, bool Ok)> CloseLegAllAsync(BasketLeg leg, long instrumentId, string basket, string basketId, string reason, List<long> stuck, List<CloseOutcome> closes, CancellationToken ct)
|
||||
{
|
||||
double weighted = 0, units = 0, pnl = 0;
|
||||
bool ok = true;
|
||||
@@ -407,9 +463,18 @@ public sealed class BasketExecutor
|
||||
CloseOutcome c = await CloseLegAsync(id, instrumentId, TrackClose(leg, basket, basketId, OrderLeg.Close, reason, id, expected), ct).ConfigureAwait(false);
|
||||
if (c.Closed)
|
||||
{
|
||||
closes.Add(c);
|
||||
double u = c.Units > 0 ? c.Units : expected;
|
||||
weighted += c.CloseRate * u;
|
||||
units += u;
|
||||
|
||||
// A close seen only on the position list has no rate: it must not drag the
|
||||
// leg's average exit towards zero. Only the closes with a price make the price.
|
||||
if (c.CloseRate > 0)
|
||||
{
|
||||
weighted += c.CloseRate * u;
|
||||
units += u;
|
||||
}
|
||||
|
||||
// NaN (unknown) makes the leg's sum unknown on purpose.
|
||||
pnl += c.RealizedPnl;
|
||||
}
|
||||
else
|
||||
@@ -422,7 +487,7 @@ public sealed class BasketExecutor
|
||||
return (units > 0 ? weighted / units : 0, pnl, ok);
|
||||
}
|
||||
|
||||
/// <summary>Three attempts with backoff; a pending outcome is re-checked against the position list.</summary>
|
||||
/// <summary>Three attempts with backoff; a pending outcome is re-checked against the position list. The outcome always names the position.</summary>
|
||||
private async Task<CloseOutcome> CloseLegAsync(long positionId, long instrumentId, TrackedOrder? track, CancellationToken ct)
|
||||
{
|
||||
if (track is not null)
|
||||
@@ -430,7 +495,7 @@ public sealed class BasketExecutor
|
||||
_tracker?.Register(track);
|
||||
}
|
||||
|
||||
CloseOutcome last = new(false, false, 0, 0, 0, DateTime.UtcNow, 0, "non tentata");
|
||||
CloseOutcome last = new(false, false, 0, 0, 0, DateTime.UtcNow, double.NaN, "non tentata") { PositionId = positionId };
|
||||
for (int attempt = 0; attempt < 3; attempt++)
|
||||
{
|
||||
try
|
||||
@@ -439,9 +504,10 @@ public sealed class BasketExecutor
|
||||
}
|
||||
catch (BrokerException ex)
|
||||
{
|
||||
last = new CloseOutcome(false, false, 0, 0, 0, DateTime.UtcNow, 0, ex.Message);
|
||||
last = new CloseOutcome(false, false, 0, 0, 0, DateTime.UtcNow, double.NaN, ex.Message);
|
||||
}
|
||||
|
||||
last = last.PositionId > 0 ? last : last with { PositionId = positionId };
|
||||
if (last.Closed)
|
||||
{
|
||||
ApplyClose(track, last);
|
||||
@@ -463,7 +529,8 @@ public sealed class BasketExecutor
|
||||
if (positions.All(x => x.PositionId != positionId))
|
||||
{
|
||||
// Gone from the account: closed by the venue (our order, or a native stop).
|
||||
last = new CloseOutcome(true, false, last.OrderId, last.CloseRate, last.Units, DateTime.UtcNow, last.RealizedPnl, string.Empty);
|
||||
// Whatever rate and result the last answer lacked stay unknown.
|
||||
last = last with { Closed = true, Rejected = false, TimeUtc = DateTime.UtcNow, Error = string.Empty };
|
||||
ApplyClose(track, last);
|
||||
return last;
|
||||
}
|
||||
@@ -480,7 +547,8 @@ public sealed class BasketExecutor
|
||||
return;
|
||||
}
|
||||
|
||||
OrderOutcome o = new(c.Closed, c.Rejected, c.OrderId, 0, c.CloseRate, c.Units, c.TimeUtc, 0, c.Closed ? "Closed" : c.Rejected ? "Rejected" : "Unknown", c.Error)
|
||||
// The close line of orders.jsonl names the position it closed (the key of the venue's history).
|
||||
OrderOutcome o = new(c.Closed, c.Rejected, c.OrderId, track.PositionId > 0 ? track.PositionId : c.PositionId, c.CloseRate, c.Units, c.TimeUtc, 0, c.Closed ? "Closed" : c.Rejected ? "Rejected" : "Unknown", c.Error)
|
||||
{
|
||||
RequestedUnits = track.RequestedUnits,
|
||||
Source = "venue",
|
||||
@@ -599,6 +667,7 @@ public sealed class BasketExecutor
|
||||
SentUtc = DateTime.UtcNow,
|
||||
Mode = _mode,
|
||||
Motivazione = (positionId > 0 ? string.Create(CultureInfo.InvariantCulture, $"posizione {positionId}: ") : string.Empty) + (reason.Length > 160 ? reason[..160] : reason),
|
||||
PositionId = positionId > 0 ? positionId : leg.PositionId,
|
||||
};
|
||||
|
||||
private OrderRequest Request(SymbolSeries s, bool isBuy, double units, double quote, string reason)
|
||||
|
||||
@@ -188,6 +188,23 @@ public sealed class BasketPosition
|
||||
|
||||
public double MaxLossUsd { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// The z stop of the preset in force at entry: a preset changed later does not move it
|
||||
/// (5.1, decision C10). NaN for a basket saved by a version before 5.1, which falls back
|
||||
/// on the preset in force.
|
||||
/// </summary>
|
||||
public double ZStop { get; init; } = double.NaN;
|
||||
|
||||
/// <summary>The adds allowed by the preset in force at entry; −1 for a basket saved before 5.1 (the preset in force decides).</summary>
|
||||
public int MaxAdds { get; init; } = -1;
|
||||
|
||||
/// <summary>
|
||||
/// The preset the basket entered with (its label, <c>MODERATE</c>): the one its <c>baskets.csv</c>
|
||||
/// row names and the bandit rewards, whatever the preset in force at the close (5.1 review).
|
||||
/// Empty for a basket saved before, which falls back on the preset in force.
|
||||
/// </summary>
|
||||
public string Preset { get; init; } = string.Empty;
|
||||
|
||||
public double EquityAtEntry { get; init; }
|
||||
|
||||
public int BarsWithBrokenCorrelation { get; set; }
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
namespace Encelado.Core.Baskets;
|
||||
|
||||
/// <summary>
|
||||
/// What a basket switched off in the strategy still does (5.1). Switching a basket off
|
||||
/// stops its entries, never its exits: a basket that is open when the switch goes off (or
|
||||
/// that the saved state brings back into a disabled slot) is still watched until it
|
||||
/// closes by its own rules — take-profit, stops, time — instead of being left to the
|
||||
/// native stop-loss on the venue alone.
|
||||
/// </summary>
|
||||
public static class BasketSlotPolicy
|
||||
{
|
||||
/// <summary>Whether the engine evaluates the slot at all: always when enabled; when disabled, only while it holds a basket.</summary>
|
||||
public static bool Evaluates(bool enabled, bool hasPosition) => enabled || hasPosition;
|
||||
|
||||
/// <summary>Whether a decision may be carried out on the slot: exits and holds always; entries and adds only when enabled.</summary>
|
||||
public static bool MayExecute(bool enabled, DecisionKind kind) => enabled || kind is not (DecisionKind.Enter or DecisionKind.Add);
|
||||
}
|
||||
@@ -143,8 +143,11 @@ public sealed class BasketDefinition
|
||||
|
||||
/// <summary>
|
||||
/// Every parameter of the strategy, from <c>strategy.json</c>. Values not in the file take
|
||||
/// the defaults written in the specification; the active preset supplies six of them and
|
||||
/// can be swapped at runtime without touching open baskets.
|
||||
/// the defaults written in the specification; the preset supplies six of them. The file
|
||||
/// is the only source of truth (5.1, decision C10): the preset is chosen in Impostazioni ▸
|
||||
/// Strategia and a saved change reaches the running engine through <see cref="CopyFrom"/>
|
||||
/// on its decision thread. A change applies to new baskets; an open basket keeps the take
|
||||
/// profit, the maximum loss, the z stop and the adds it entered with.
|
||||
/// </summary>
|
||||
public sealed class BasketStrategyConfig
|
||||
{
|
||||
@@ -295,6 +298,137 @@ public sealed class BasketStrategyConfig
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Whether <paramref name="other"/> trades the same instruments: the same baskets, in
|
||||
/// the same order, on the same pairs, and the same choice about the direct crosses.
|
||||
/// These are what the engine builds its series and slots from at start; anything else
|
||||
/// can change under a running engine (<see cref="CopyFrom"/>), these need a restart.
|
||||
/// </summary>
|
||||
public bool SameStructure(BasketStrategyConfig other)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(other);
|
||||
return PreferDirectCross == other.PreferDirectCross && SameBaskets(other);
|
||||
}
|
||||
|
||||
/// <summary>The same pairs in the same order (the enable switches and the notes may differ).</summary>
|
||||
private bool SameBaskets(BasketStrategyConfig other)
|
||||
{
|
||||
if (Baskets.Count != other.Baskets.Count)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
for (int i = 0; i < Baskets.Count; i++)
|
||||
{
|
||||
if (!Baskets[i].A.Equals(other.Baskets[i].A, StringComparison.OrdinalIgnoreCase) ||
|
||||
!Baskets[i].B.Equals(other.Baskets[i].B, StringComparison.OrdinalIgnoreCase))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Copies every value of <paramref name="source"/> into this instance, in place: the
|
||||
/// decider, the executor and the learning state hold this very object, so they read
|
||||
/// the new values at their next use. The nested sections are updated field by field
|
||||
/// (a reference taken to them stays valid), and so are the baskets when the structure
|
||||
/// is the same (the engine's slots hold those definitions); a different list is
|
||||
/// replaced, which only a fresh engine may see.
|
||||
/// </summary>
|
||||
public void CopyFrom(BasketStrategyConfig source)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(source);
|
||||
if (ReferenceEquals(source, this))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
bool sameBaskets = SameBaskets(source);
|
||||
Preset = source.Preset;
|
||||
SignalMode = source.SignalMode;
|
||||
ExitMode = source.ExitMode;
|
||||
AveragingMode = source.AveragingMode;
|
||||
TpMode = source.TpMode;
|
||||
SameCrossPolicy = source.SameCrossPolicy;
|
||||
PreferDirectCross = source.PreferDirectCross;
|
||||
InvertSignal = source.InvertSignal;
|
||||
Window = source.Window;
|
||||
WindowShort = source.WindowShort;
|
||||
RhoMin = source.RhoMin;
|
||||
RhoShortMin = source.RhoShortMin;
|
||||
HalfLifeMinBars = source.HalfLifeMinBars;
|
||||
HalfLifeMaxBars = source.HalfLifeMaxBars;
|
||||
HalfLifeRecalcHours = source.HalfLifeRecalcHours;
|
||||
AtrPeriod = source.AtrPeriod;
|
||||
EwmaSpan = source.EwmaSpan;
|
||||
TrendPeriod = source.TrendPeriod;
|
||||
ZOut = source.ZOut;
|
||||
DIn = source.DIn;
|
||||
AnchorBars = source.AnchorBars;
|
||||
GridStepZ = source.GridStepZ;
|
||||
LotMultiplier = source.LotMultiplier;
|
||||
MaxLossPerBasketPct = source.MaxLossPerBasketPct;
|
||||
RhoBreak = source.RhoBreak;
|
||||
RhoBreakBars = source.RhoBreakBars;
|
||||
MaxHoldingBars = source.MaxHoldingBars;
|
||||
TpAtrMultiple = source.TpAtrMultiple;
|
||||
CostMultiple = source.CostMultiple;
|
||||
SpreadMedianMultiple = source.SpreadMedianMultiple;
|
||||
SpreadAnomalyMultiple = source.SpreadAnomalyMultiple;
|
||||
SlippagePipsPerLeg = source.SlippagePipsPerLeg;
|
||||
OvernightPipsPerDay = source.OvernightPipsPerDay;
|
||||
BlackoutBeforeMin = source.BlackoutBeforeMin;
|
||||
BlackoutAfterMin = source.BlackoutAfterMin;
|
||||
FridayCutoffUtcHour = source.FridayCutoffUtcHour;
|
||||
OpenDelayMinutes = source.OpenDelayMinutes;
|
||||
Sessions = [.. source.Sessions];
|
||||
MaxEffectiveLeverage = source.MaxEffectiveLeverage;
|
||||
OrderLeverage = source.OrderLeverage;
|
||||
VolScaleMin = source.VolScaleMin;
|
||||
VolScaleMax = source.VolScaleMax;
|
||||
VolAverageDays = source.VolAverageDays;
|
||||
MlMinProbability = source.MlMinProbability;
|
||||
EquityStopPct = source.EquityStopPct;
|
||||
DailyLossPct = source.DailyLossPct;
|
||||
LegTimeoutSec = source.LegTimeoutSec;
|
||||
ClockSkewMaxSeconds = source.ClockSkewMaxSeconds;
|
||||
ZInOverride = source.ZInOverride;
|
||||
RiskPerBasketPctOverride = source.RiskPerBasketPctOverride;
|
||||
MaxBasketsOverride = source.MaxBasketsOverride;
|
||||
TpPipsOverride = source.TpPipsOverride;
|
||||
MaxAddsOverride = source.MaxAddsOverride;
|
||||
ZStopOverride = source.ZStopOverride;
|
||||
|
||||
Risk.MaxMarginUsePct = source.Risk.MaxMarginUsePct;
|
||||
Risk.MaxMarginPerBasketPct = source.Risk.MaxMarginPerBasketPct;
|
||||
Risk.MarginBufferPct = source.Risk.MarginBufferPct;
|
||||
Risk.CloseForeignOnKill = source.Risk.CloseForeignOnKill;
|
||||
Risk.MarginCallBlockRatio = source.Risk.MarginCallBlockRatio;
|
||||
Risk.MarginCallCloseRatio = source.Risk.MarginCallCloseRatio;
|
||||
Recovery.ThresholdMinutes = source.Recovery.ThresholdMinutes;
|
||||
Recovery.WarmupMinutes = source.Recovery.WarmupMinutes;
|
||||
Recovery.HeartbeatSeconds = source.Recovery.HeartbeatSeconds;
|
||||
Learning.Enabled = source.Learning.Enabled;
|
||||
Learning.WeeklyCycle = source.Learning.WeeklyCycle;
|
||||
Learning.Challenger = source.Learning.Challenger;
|
||||
|
||||
if (sameBaskets)
|
||||
{
|
||||
for (int i = 0; i < Baskets.Count; i++)
|
||||
{
|
||||
Baskets[i].Enabled = source.Baskets[i].Enabled;
|
||||
Baskets[i].Note = source.Baskets[i].Note;
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
Baskets = [.. source.Baskets.Select(static b => new BasketDefinition { A = b.A, B = b.B, Enabled = b.Enabled, Note = b.Note })];
|
||||
}
|
||||
}
|
||||
|
||||
public static List<BasketDefinition> DefaultBaskets() =>
|
||||
[
|
||||
new() { A = "EURUSD", B = "USDCHF", Note = "cross sintetico EURCHF" },
|
||||
@@ -686,14 +820,14 @@ public sealed class BasketStrategyConfig
|
||||
{
|
||||
"_comment": "Encelado — strategia Correlation Baskets su eToro. Cinque basket di due coppie forex correlate: si entra quando il cross sintetico diverge (z-score), si esce quando converge o al take-profit di basket in pip; lo stop di basket è obbligatorio. Ogni chiave con '_' davanti è documentazione.",
|
||||
|
||||
"_preset": "Conservative | Moderate | Aggressive. Fissa zIn, riskPerBasketPct, maxBaskets, tpPips, maxAdds, zStop; si cambia a caldo dalla finestra senza toccare i basket aperti. Le chiavi omonime qui sotto, se presenti, sovrascrivono il preset.",
|
||||
"_preset": "Conservative | Moderate | Aggressive. Fissa zIn, riskPerBasketPct, maxBaskets, tpPips, maxAdds, zStop. Si sceglie in Impostazioni ▸ Strategia e il bot lo applica subito ai basket nuovi: quelli già aperti tengono take-profit, perdita massima, zStop e aggiunte con cui sono entrati. Le chiavi omonime qui sotto, se presenti, sovrascrivono il preset.",
|
||||
"preset": "Moderate",
|
||||
|
||||
"_signalMode": "ZScoreSynthetic (default, |z| >= zIn sul cross sintetico) oppure PipDivergence (fedele all'interfaccia Titany: divergenza in pip dall'ancora, dIn).",
|
||||
"signalMode": "ZScoreSynthetic",
|
||||
"_exitMode": "First = la prima fra TP in pip e rientro dello z; FixedPips = solo TP in pip lordi; ZReturn = solo |z| <= zOut.",
|
||||
"exitMode": "First",
|
||||
"_averagingMode": "Off | AddOnce | Grid. Off in live; AddOnce in paper. Moltiplicatore di lotto sempre 1,0 (niente martingala).",
|
||||
"_averagingMode": "Off | AddOnce | Grid. Off di fabbrica; AddOnce ammette una sola aggiunta per basket, Grid fino a maxAdds. Moltiplicatore di lotto sempre 1,0 (niente martingala).",
|
||||
"averagingMode": "Off",
|
||||
"tpMode": "Pips",
|
||||
"_sameCrossPolicy": "I basket 4 e 5 sono entrambi EURCAD: Exclusive = uno solo aperto per volta; Half = entrambi a metà size.",
|
||||
@@ -748,13 +882,13 @@ public sealed class BasketStrategyConfig
|
||||
"volAverageDays": 30,
|
||||
"mlMinProbability": 0.55,
|
||||
|
||||
"_sicurezza": "equityStopPct: perdita dal picco di equity (al netto dei movimenti di cassa) oltre la quale il bot chiude tutto e si blocca (reset manuale con motivazione). dailyLossPct: perdita giornaliera oltre la quale niente nuove entrate fino al giorno dopo.",
|
||||
"_sicurezza": "equityStopPct: perdita dal picco di equity (al netto dei movimenti di cassa) oltre la quale il bot chiude tutto e si blocca (reset manuale con motivazione). dailyLossPct: perdita giornaliera oltre la quale niente nuove entrate fino alle 00:00 UTC, anche se poi l'equity recupera.",
|
||||
"equityStopPct": 9,
|
||||
"dailyLossPct": 3,
|
||||
"legTimeoutSec": 5,
|
||||
"clockSkewMaxSeconds": 5,
|
||||
|
||||
"_risk": "Margine (5.0, §10). La size di un basket è il minimo fra la size a rischio e quella a margine. maxMarginUsePct: margine totale impegnato dopo l'apertura, in % dell'equity. maxMarginPerBasketPct: margine delle due gambe di un basket, in % dell'equity. marginBufferPct: il disponibile deve superare il margine richiesto di questa percentuale prima di inviare A e, ricontrollato, prima di inviare B (altrimenti A viene richiusa). closeForeignOnKill: il kill-switch chiude anche le posizioni non aperte dal bot. marginCallBlockRatio / marginCallCloseRatio: sotto equity/margine usato = 1,5 niente entrate; sotto 1,2 si chiude il basket con il P&L peggiore.",
|
||||
"_risk": "Margine (5.0, §10). La size di un basket è il minimo fra la size a rischio e quella a margine. maxMarginUsePct: margine totale impegnato dopo l'apertura, in % dell'equity. maxMarginPerBasketPct: margine delle due gambe di un basket, in % dell'equity. marginBufferPct: il disponibile deve superare il margine richiesto di questa percentuale prima di inviare A e, ricontrollato, prima di inviare B (altrimenti A viene richiusa). closeForeignOnKill: il kill-switch chiude anche le posizioni non aperte dal bot (Telegram /kill, file STOP); nel dialogo del kill-switch è solo la scelta di partenza della casella. marginCallBlockRatio / marginCallCloseRatio: sotto equity/margine usato = 1,5 niente entrate; sotto 1,2 si chiude il basket con il P&L peggiore.",
|
||||
"risk": {
|
||||
"maxMarginUsePct": 40,
|
||||
"maxMarginPerBasketPct": 12,
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
namespace Encelado.Core.Baskets;
|
||||
|
||||
/// <summary>
|
||||
/// The daily-loss rule of <c>docs/RISK_RULES.md</c>, one formula for the live engine and
|
||||
/// the backtest: the net equity (cash movements excluded) lost since 00:00 UTC reaches
|
||||
/// <c>dailyLossPct</c> % of the net equity the day started with. It looks at equity, so
|
||||
/// realised and unrealised results both count and a deposit cannot hide a loss. Once hit,
|
||||
/// the block holds until 00:00 UTC (<see cref="DailyLossLatch"/>).
|
||||
/// </summary>
|
||||
public static class DailyLoss
|
||||
{
|
||||
/// <summary><c>dayStart − now ≥ dayStart × dailyLossPct / 100</c>; false while either number is unknown.</summary>
|
||||
public static bool IsHit(double dayStartNetEquity, double netEquityNow, double dailyLossPct) =>
|
||||
dayStartNetEquity > 0 && double.IsFinite(netEquityNow) && dailyLossPct > 0 &&
|
||||
dayStartNetEquity - netEquityNow >= dayStartNetEquity * dailyLossPct / 100.0;
|
||||
|
||||
/// <summary>How much of the day's loss budget is used, between 0 and 1; NaN while unknown.</summary>
|
||||
public static double UsedFraction(double dayStartNetEquity, double netEquityNow, double dailyLossPct)
|
||||
{
|
||||
if (!(dayStartNetEquity > 0) || !double.IsFinite(netEquityNow) || !(dailyLossPct > 0))
|
||||
{
|
||||
return double.NaN;
|
||||
}
|
||||
|
||||
double budget = dayStartNetEquity * dailyLossPct / 100.0;
|
||||
return Math.Clamp((dayStartNetEquity - netEquityNow) / budget, 0, 1);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The daily-loss block (D-52): once the rule of <see cref="DailyLoss"/> is hit, no new entry
|
||||
/// and no add until 00:00 UTC, even if the equity recovers meanwhile. The live engine keeps one
|
||||
/// per account (its day goes in the account's state, so a restart keeps the block), the
|
||||
/// backtest one per replay (<see cref="Backtest.ReplayDailyLoss"/>). A latch of another day blocks nothing.
|
||||
/// </summary>
|
||||
public sealed class DailyLossLatch
|
||||
{
|
||||
/// <summary>The UTC day the rule was hit; default when it was not.</summary>
|
||||
public DateOnly Day { get; private set; }
|
||||
|
||||
/// <summary>True while the block holds on <paramref name="today"/>.</summary>
|
||||
public bool IsLatched(DateOnly today) => Day != default && Day == today;
|
||||
|
||||
/// <summary>
|
||||
/// The rule on <paramref name="today"/>'s numbers: a hit latches the day. True when the rule
|
||||
/// is hit now or was hit earlier the same day, never less than the rule itself.
|
||||
/// </summary>
|
||||
public bool Evaluate(DateOnly today, double dayStartNetEquity, double netEquityNow, double dailyLossPct)
|
||||
{
|
||||
bool hit = DailyLoss.IsHit(dayStartNetEquity, netEquityNow, dailyLossPct);
|
||||
if (hit && today != default)
|
||||
{
|
||||
Day = today;
|
||||
}
|
||||
|
||||
return hit || IsLatched(today);
|
||||
}
|
||||
|
||||
/// <summary>The day read back from a saved state: it is kept only while it is still <paramref name="today"/> (the block ends at 00:00 UTC).</summary>
|
||||
public void Restore(DateOnly day, DateOnly today) => Day = day != default && day == today ? day : default;
|
||||
}
|
||||
@@ -47,10 +47,18 @@ public sealed class EquityTracker
|
||||
/// <summary>
|
||||
/// Records an account reading. <paramref name="closedNetSinceLast"/> is the realised
|
||||
/// net result (profit minus fees) of the positions closed since the previous reading,
|
||||
/// which is the only legitimate reason for the cash balance to move.
|
||||
/// which is the only legitimate reason for the cash balance to move. NaN means the
|
||||
/// venue has not explained those closes yet (its history lags): no verdict is given,
|
||||
/// the previous balance stays the reference so the next explained reading judges the
|
||||
/// whole difference, and the peak does not move (an unbooked deposit must not raise it).
|
||||
/// </summary>
|
||||
public CashMovement? Observe(DateTime now, double balance, double equity, double closedNetSinceLast)
|
||||
{
|
||||
if (!double.IsFinite(closedNetSinceLast))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
CashMovement? movement = null;
|
||||
if (double.IsFinite(LastBalance))
|
||||
{
|
||||
@@ -78,6 +86,22 @@ public sealed class EquityTracker
|
||||
/// <summary>After a reset the peak restarts from the current equity.</summary>
|
||||
public void ResetPeak(double equity) => PeakNetEquity = NetEquity(equity);
|
||||
|
||||
/// <summary>
|
||||
/// Takes the balance as the new reference without judging the difference: used at
|
||||
/// startup when the history of the closes made while the bot was off cannot be read,
|
||||
/// so their result is never booked as a deposit or a withdrawal.
|
||||
/// </summary>
|
||||
public void Rebase(DateTime now, double balance, double equity)
|
||||
{
|
||||
LastBalance = balance;
|
||||
LastObservedUtc = now;
|
||||
double net = NetEquity(equity);
|
||||
if (net > PeakNetEquity)
|
||||
{
|
||||
PeakNetEquity = net;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Restores the persisted state; a peak saved by a version that knew no cash flows is taken as a net peak.</summary>
|
||||
public void Restore(double peakNetEquity, double cumulativeCashFlow, double lastBalance, DateTime lastObservedUtc)
|
||||
{
|
||||
|
||||
@@ -1,17 +1,24 @@
|
||||
namespace Encelado.Core.Baskets;
|
||||
|
||||
/// <summary>
|
||||
/// Who fills the orders. The bot runs unattended in every mode: it opens and closes
|
||||
/// baskets by itself. The default is <see cref="Demo"/>: real orders on eToro's demo
|
||||
/// account, virtual money. <see cref="Live"/> needs the configuration flag and the typed
|
||||
/// phrase at start (decision D-20, 2026-09-16: no manual approval of single orders).
|
||||
/// Who fills the orders, and on which eToro account. The bot runs unattended in both
|
||||
/// modes: it opens and closes baskets by itself. The default is <see cref="Demo"/>: real
|
||||
/// orders on eToro's demo account, virtual money. <see cref="Live"/> is the real account
|
||||
/// and needs the configuration flag and the phrase typed in the interface at every start
|
||||
/// (decision D-20, 2026-09-16: no manual approval of single orders). The mode also picks
|
||||
/// the account: there is no separate environment setting (5.1, decision C6), so a demo
|
||||
/// mode can never send orders to the real account.
|
||||
/// <para>
|
||||
/// The explicit values keep the numbers of the previous versions (Paper was 1 and is
|
||||
/// gone: the eToro demo account is the simulator). Nothing stores the number; the
|
||||
/// ledger, the state and the heartbeat store the name.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public enum ExecutionMode
|
||||
{
|
||||
Backtest = 0,
|
||||
Paper,
|
||||
Demo,
|
||||
Live,
|
||||
Demo = 2,
|
||||
Live = 3,
|
||||
}
|
||||
|
||||
public static class ExecutionModeExtensions
|
||||
@@ -22,33 +29,51 @@ public static class ExecutionModeExtensions
|
||||
|
||||
public static bool UsesVenue(this ExecutionMode m) => m is ExecutionMode.Demo or ExecutionMode.Live;
|
||||
|
||||
/// <summary>The label shown in the badge: PAPER, DEMO, LIVE or BACKTEST.</summary>
|
||||
/// <summary>The label shown in the badge: DEMO, LIVE or BACKTEST.</summary>
|
||||
public static string Badge(this ExecutionMode m) => m switch
|
||||
{
|
||||
ExecutionMode.Paper => "PAPER",
|
||||
ExecutionMode.Demo => "DEMO",
|
||||
ExecutionMode.Live => "LIVE",
|
||||
_ => "BACKTEST",
|
||||
};
|
||||
|
||||
/// <summary><c>paper</c>, <c>demo</c>, <c>live</c> or <c>backtest</c>, for the badge colour.</summary>
|
||||
/// <summary><c>demo</c>, <c>live</c> or <c>backtest</c>, for the badge colour.</summary>
|
||||
public static string Kind(this ExecutionMode m) => m.Badge().ToLowerInvariant();
|
||||
|
||||
/// <summary>Whether <paramref name="text"/> is a mode name of a previous version (the approve/auto pairs), which still parse.</summary>
|
||||
public static bool IsLegacyName(string? text) => Normalise(text) is "demoapprove" or "demoauto" or "liveapprove" or "liveauto";
|
||||
/// <summary>The eToro account a mode trades on: <c>demo</c> or <c>live</c> (the API's words).</summary>
|
||||
public static string Account(this ExecutionMode m) => m.IsLive() ? "live" : "demo";
|
||||
|
||||
/// <summary>
|
||||
/// Whether <paramref name="text"/> is a mode name of a previous version, which still
|
||||
/// parses: the approve/auto pairs of 4.0 and <c>Paper</c>, read as Demo since 5.1.
|
||||
/// </summary>
|
||||
public static bool IsLegacyName(string? text) => Normalise(text) is "demoapprove" or "demoauto" or "liveapprove" or "liveauto" or "paper";
|
||||
|
||||
public static bool TryParse(string? text, out ExecutionMode mode)
|
||||
{
|
||||
switch (Normalise(text))
|
||||
{
|
||||
case "backtest": mode = ExecutionMode.Backtest; return true;
|
||||
case "paper": mode = ExecutionMode.Paper; return true;
|
||||
case "demo" or "demoapprove" or "demoauto": mode = ExecutionMode.Demo; return true;
|
||||
case "demo" or "demoapprove" or "demoauto" or "paper": mode = ExecutionMode.Demo; return true;
|
||||
case "live" or "real" or "liveapprove" or "liveauto": mode = ExecutionMode.Live; return true;
|
||||
default: mode = ExecutionMode.Demo; return false;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The merge rule of 5.1 for files and containers of 5.0, where mode and account were
|
||||
/// two settings: the result is Live only when the mode said Live <b>and</b> the account
|
||||
/// said real; every other combination is Demo. Demo + real (orders to the real account
|
||||
/// without the Live gate) and Live + demo both become Demo. <paramref name="disagree"/>
|
||||
/// is true when the two inputs did not say the same thing.
|
||||
/// </summary>
|
||||
public static ExecutionMode Merge(ExecutionMode mode, string? environment, out bool disagree)
|
||||
{
|
||||
bool real = (environment ?? "demo").Trim().Equals("real", StringComparison.OrdinalIgnoreCase);
|
||||
disagree = mode.IsLive() != real;
|
||||
return mode.IsLive() && real ? ExecutionMode.Live : ExecutionMode.Demo;
|
||||
}
|
||||
|
||||
private static string Normalise(string? text) =>
|
||||
(text ?? string.Empty).Trim().Replace("-", string.Empty, StringComparison.Ordinal).Replace("_", string.Empty, StringComparison.Ordinal).ToLowerInvariant();
|
||||
}
|
||||
@@ -6,7 +6,7 @@ namespace Encelado.Core.Baskets;
|
||||
/// <summary>A position the kill-switch must close, with what it is for the report.</summary>
|
||||
public sealed record FlattenTarget(long PositionId, long InstrumentId, string Symbol, bool IsBuy, double Units, string Basket, string Kind);
|
||||
|
||||
/// <summary>What the kill-switch did and what is left.</summary>
|
||||
/// <summary>What the kill-switch did and what is left. <see cref="RealizedPnlUsd"/> sums only the closes whose result the venue gave; <see cref="UnknownPnl"/> counts the others (eToro: all of them, settled later from the history).</summary>
|
||||
public sealed record FlattenReport(
|
||||
IReadOnlyList<long> CancelledOrders,
|
||||
IReadOnlyList<long> OrdersFilledMeanwhile,
|
||||
@@ -18,6 +18,21 @@ public sealed record FlattenReport(
|
||||
{
|
||||
/// <summary>The engine's state after the procedure: <c>Halted</c> when flat, <c>Halted-Residuo</c> otherwise.</summary>
|
||||
public string State => Flat ? "Halted" : "Halted-Residuo";
|
||||
|
||||
/// <summary>Closes whose realised result is not known yet.</summary>
|
||||
public int UnknownPnl { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// What closing the targets did: the ids closed and refused, the realised result of the
|
||||
/// closes that carried one (never a NaN read as zero), how many carried none, and every
|
||||
/// close as the venue answered it.
|
||||
/// </summary>
|
||||
public sealed record FlattenCloses(List<long> Closed, List<long> Failed, double RealizedKnown, int UnknownPnl, IReadOnlyList<(FlattenTarget Target, CloseOutcome Close)> Outcomes)
|
||||
{
|
||||
/// <summary>The realised part as text: the known sum, and how many wait for the venue's history.</summary>
|
||||
public string Describe() => string.Create(CultureInfo.InvariantCulture,
|
||||
$"{RealizedKnown:+0.00;-0.00} USD noti{(UnknownPnl > 0 ? $", {UnknownPnl} da confermare con lo storico eToro" : string.Empty)}");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
@@ -116,8 +131,12 @@ public sealed class FlattenProcedure(IBroker broker, OrderTracker tracker, Actio
|
||||
return (cancelled, filled);
|
||||
}
|
||||
|
||||
/// <summary>Step 2. Closes every target through <paramref name="closer"/>; returns the ids closed, the ids that refused, and the realised result.</summary>
|
||||
public static async Task<(List<long> Closed, List<long> Failed, double Realized)> CloseTargetsAsync(
|
||||
/// <summary>
|
||||
/// Step 2. Closes every target through <paramref name="closer"/>. The realised result
|
||||
/// sums only the closes that carried one; a close without it (eToro's, always) is
|
||||
/// counted apart and settled later from the venue's history.
|
||||
/// </summary>
|
||||
public static async Task<FlattenCloses> CloseTargetsAsync(
|
||||
IReadOnlyList<FlattenTarget> targets, Func<FlattenTarget, CancellationToken, Task<CloseOutcome>> closer, Action<string> log, CancellationToken ct)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(targets);
|
||||
@@ -125,7 +144,9 @@ public sealed class FlattenProcedure(IBroker broker, OrderTracker tracker, Actio
|
||||
ArgumentNullException.ThrowIfNull(log);
|
||||
List<long> closed = [];
|
||||
List<long> failed = [];
|
||||
List<(FlattenTarget, CloseOutcome)> outcomes = [];
|
||||
double realized = 0;
|
||||
int unknown = 0;
|
||||
foreach (FlattenTarget t in targets)
|
||||
{
|
||||
CloseOutcome c;
|
||||
@@ -135,14 +156,26 @@ public sealed class FlattenProcedure(IBroker broker, OrderTracker tracker, Actio
|
||||
}
|
||||
catch (BrokerException ex)
|
||||
{
|
||||
c = new CloseOutcome(false, false, 0, 0, 0, DateTime.UtcNow, 0, ex.Message);
|
||||
c = new CloseOutcome(false, false, 0, 0, 0, DateTime.UtcNow, double.NaN, ex.Message);
|
||||
}
|
||||
|
||||
outcomes.Add((t, c.PositionId > 0 ? c : c with { PositionId = t.PositionId }));
|
||||
if (c.Closed)
|
||||
{
|
||||
closed.Add(t.PositionId);
|
||||
realized += c.RealizedPnl;
|
||||
log(string.Create(CultureInfo.InvariantCulture, $"kill-switch: chiusa {t.Kind} {t.PositionId} {t.Symbol} {(t.IsBuy ? "long" : "short")} {t.Units:0.##} ({c.RealizedPnl:+0.00;-0.00} USD)"));
|
||||
string pnl;
|
||||
if (double.IsFinite(c.RealizedPnl))
|
||||
{
|
||||
realized += c.RealizedPnl;
|
||||
pnl = c.RealizedPnl.ToString("+0.00;-0.00", CultureInfo.InvariantCulture) + " USD";
|
||||
}
|
||||
else
|
||||
{
|
||||
unknown++;
|
||||
pnl = "P&L dallo storico eToro";
|
||||
}
|
||||
|
||||
log(string.Create(CultureInfo.InvariantCulture, $"kill-switch: chiusa {t.Kind} {t.PositionId} {t.Symbol} {(t.IsBuy ? "long" : "short")} {t.Units:0.##} ({pnl})"));
|
||||
}
|
||||
else
|
||||
{
|
||||
@@ -151,7 +184,7 @@ public sealed class FlattenProcedure(IBroker broker, OrderTracker tracker, Actio
|
||||
}
|
||||
}
|
||||
|
||||
return (closed, failed, realized);
|
||||
return new FlattenCloses(closed, failed, realized, unknown, outcomes);
|
||||
}
|
||||
|
||||
/// <summary>Step 3. Re-reads the positions until none of <paramref name="mustBeGone"/> is there, or the timeout passes. Returns what is left.</summary>
|
||||
@@ -197,12 +230,12 @@ public sealed class FlattenProcedure(IBroker broker, OrderTracker tracker, Actio
|
||||
}
|
||||
}
|
||||
|
||||
(List<long> closed, List<long> failed, double realized) = await CloseTargetsAsync(all, closer, _log, ct).ConfigureAwait(false);
|
||||
FlattenCloses closes = await CloseTargetsAsync(all, closer, _log, ct).ConfigureAwait(false);
|
||||
List<long> residue = await VerifyFlatAsync([.. all.Select(static t => t.PositionId)], ct).ConfigureAwait(false);
|
||||
bool flat = residue.Count == 0;
|
||||
string summary = string.Create(CultureInfo.InvariantCulture,
|
||||
$"{closed.Count} posizioni chiuse su {all.Count} ({realized:+0.00;-0.00} USD), {cancelled.Count} ordini annullati, {filledMeanwhile.Count} eseguiti nel frattempo, {_tracker.PendingCount} ancora senza esito; {(flat ? "conto piatto per le posizioni del bot" : $"RESIDUO: {string.Join(", ", residue)}")}");
|
||||
return new FlattenReport(cancelled, [.. filledMeanwhile.Select(static p => p.PositionId)], closed, residue, realized, flat, summary);
|
||||
$"{closes.Closed.Count} posizioni chiuse su {all.Count} ({closes.Describe()}), {cancelled.Count} ordini annullati, {filledMeanwhile.Count} eseguiti nel frattempo, {_tracker.PendingCount} ancora senza esito; {(flat ? "conto piatto per le posizioni del bot" : $"RESIDUO: {string.Join(", ", residue)}")}");
|
||||
return new FlattenReport(cancelled, [.. filledMeanwhile.Select(static p => p.PositionId)], closes.Closed, residue, closes.RealizedKnown, flat, summary) { UnknownPnl = closes.UnknownPnl };
|
||||
}
|
||||
|
||||
/// <summary>The reset's first gate: a written reason of at least ten characters.</summary>
|
||||
|
||||
@@ -2,7 +2,13 @@ using System.Globalization;
|
||||
|
||||
namespace Encelado.Core.Baskets.History;
|
||||
|
||||
/// <summary>One closed basket as <c>baskets.csv</c> records it.</summary>
|
||||
/// <summary>
|
||||
/// One closed basket (or lone leg) as <c>baskets.csv</c> records it. From 5.1 the P&L
|
||||
/// columns hold the venue's history (netProfit − fees of the row's positions), or an
|
||||
/// estimate flagged <c>P&L: stima</c> in the motivation when the history did not show
|
||||
/// them in time. Rows are never edited: <see cref="Unverified"/> and <see cref="Corrected"/>
|
||||
/// are set by the corrected reader from the correction lines of <c>decisions.jsonl</c>.
|
||||
/// </summary>
|
||||
public sealed record BasketOutcomeRow(
|
||||
string BasketId,
|
||||
string RunId,
|
||||
@@ -29,6 +35,18 @@ public sealed record BasketOutcomeRow(
|
||||
{
|
||||
public int Label => PnlNetUsd > 0 ? 1 : 0;
|
||||
|
||||
/// <summary>The P&L was not established from the venue (an estimate, or positions the history does not show): no label, out of training and of the reports. Never written to the file.</summary>
|
||||
public bool Unverified { get; init; }
|
||||
|
||||
/// <summary>A correction line was applied by the corrected reader. Never written to the file.</summary>
|
||||
public bool Corrected { get; init; }
|
||||
|
||||
/// <summary>The row may teach and be summed: its P&L is known and verified.</summary>
|
||||
public bool HasLabel => !Unverified && double.IsFinite(PnlNetUsd);
|
||||
|
||||
/// <summary>A lone leg (an unwind, an orphan): no entry z, not a basket.</summary>
|
||||
public bool IsLoneLeg => !double.IsFinite(EntryZ);
|
||||
|
||||
public const string Header =
|
||||
"basket_id;run_id;basket;mode;preset;opened_utc;closed_utc;buy_cross;entry_z;exit_z;pnl_gross_usd;pnl_net_usd;pips_gross;cost_pips;cost_usd;slippage_pips;adds;bars_held;exit_reason;equity_at_entry;p_ml_at_entry;label;durata_min;motivazione";
|
||||
|
||||
@@ -38,7 +56,7 @@ public sealed record BasketOutcomeRow(
|
||||
OpenedUtc.ToString("O", CultureInfo.InvariantCulture), ClosedUtc.ToString("O", CultureInfo.InvariantCulture),
|
||||
BuyCross ? "1" : "0", N(EntryZ), N(ExitZ), N(PnlGrossUsd), N(PnlNetUsd), N(PipsGross), N(CostPips), N(CostUsd), N(SlippagePips),
|
||||
Adds.ToString(CultureInfo.InvariantCulture), BarsHeld.ToString(CultureInfo.InvariantCulture), ExitReason, N(EquityAtEntry), N(PMlAtEntry),
|
||||
Label.ToString(CultureInfo.InvariantCulture), ((ClosedUtc - OpenedUtc).TotalMinutes).ToString("0", CultureInfo.InvariantCulture),
|
||||
double.IsFinite(PnlNetUsd) ? Label.ToString(CultureInfo.InvariantCulture) : string.Empty, ((ClosedUtc - OpenedUtc).TotalMinutes).ToString("0", CultureInfo.InvariantCulture),
|
||||
Motivazione.Replace(';', ',').Replace('\n', ' ').Replace('\r', ' '),
|
||||
]);
|
||||
|
||||
|
||||
@@ -96,48 +96,43 @@ public static class HistoryBuilder
|
||||
Func<string, double> pipOf,
|
||||
DateTime nowUtc)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(closed);
|
||||
ArgumentNullException.ThrowIfNull(open);
|
||||
ArgumentNullException.ThrowIfNull(baskets);
|
||||
ArgumentNullException.ThrowIfNull(orders);
|
||||
return Positions(closed, open, new PositionOrigins(orders, baskets), cash, symbolOf, pipOf, nowUtc);
|
||||
}
|
||||
|
||||
/// <summary>The same, with the owner of each position decided by an index the caller already holds.</summary>
|
||||
public static List<PositionRecord> Positions(
|
||||
IReadOnlyList<ClosedTrade> closed,
|
||||
IReadOnlyList<BrokerPosition> open,
|
||||
PositionOrigins origins,
|
||||
IReadOnlyList<CashMovementRecord> cash,
|
||||
Func<long, string> symbolOf,
|
||||
Func<string, double> pipOf,
|
||||
DateTime nowUtc)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(closed);
|
||||
ArgumentNullException.ThrowIfNull(open);
|
||||
ArgumentNullException.ThrowIfNull(origins);
|
||||
ArgumentNullException.ThrowIfNull(cash);
|
||||
ArgumentNullException.ThrowIfNull(symbolOf);
|
||||
ArgumentNullException.ThrowIfNull(pipOf);
|
||||
|
||||
// Whose is each position id: the last order line that produced it.
|
||||
Dictionary<long, OrderRecord> byPosition = [];
|
||||
foreach (OrderRecord o in orders)
|
||||
{
|
||||
if (o.PositionId > 0 && o.Leg is not (OrderLeg.Close or OrderLeg.Unwind))
|
||||
{
|
||||
byPosition[o.PositionId] = o;
|
||||
}
|
||||
}
|
||||
|
||||
Dictionary<string, BasketOutcomeRow> byBasketId = new(StringComparer.Ordinal);
|
||||
foreach (BasketOutcomeRow b in baskets)
|
||||
{
|
||||
if (b.BasketId.Length > 0)
|
||||
{
|
||||
byBasketId[b.BasketId] = b;
|
||||
}
|
||||
}
|
||||
|
||||
List<PositionRecord> rows = [];
|
||||
foreach (ClosedTrade t in closed)
|
||||
{
|
||||
string symbol = symbolOf(t.InstrumentId);
|
||||
(string origin, string basketId, string basket, string exit) = Classify(t.PositionId, t.OpenedUtc, byPosition, byBasketId, baskets);
|
||||
(string origin, string basketId, string basket, string exit) = origins.Classify(t.PositionId);
|
||||
double pip = pipOf(symbol);
|
||||
double pips = pip > 0 ? (t.IsBuy ? t.CloseRate - t.OpenRate : t.OpenRate - t.CloseRate) / pip : double.NaN;
|
||||
rows.Add(new PositionRecord(t.PositionId, symbol, t.IsBuy, t.Units, t.OpenRate, t.CloseRate, t.OpenedUtc, t.ClosedUtc,
|
||||
t.NetProfit, t.Fees, t.NetProfit - t.Fees, pips, origin, basketId, basket, exit, false, origin == "esterna" ? "posizione non aperta dal bot" : string.Empty));
|
||||
t.NetProfit, t.Fees, t.NetUsd, pips, origin, basketId, basket, exit, false, origin == PositionOwner.ForeignOrigin ? "posizione non aperta dal bot" : string.Empty));
|
||||
}
|
||||
|
||||
foreach (BrokerPosition p in open)
|
||||
{
|
||||
string symbol = symbolOf(p.InstrumentId);
|
||||
(string origin, string basketId, string basket, _) = Classify(p.PositionId, p.OpenedUtc, byPosition, byBasketId, baskets);
|
||||
(string origin, string basketId, string basket, _) = origins.Classify(p.PositionId);
|
||||
double pip = pipOf(symbol);
|
||||
double pips = pip > 0 && p.CurrentRate > 0 ? (p.IsBuy ? p.CurrentRate - p.OpenRate : p.OpenRate - p.CurrentRate) / pip : double.NaN;
|
||||
rows.Add(new PositionRecord(p.PositionId, symbol, p.IsBuy, p.Units, p.OpenRate, p.CurrentRate, p.OpenedUtc, null,
|
||||
@@ -154,31 +149,6 @@ public static class HistoryBuilder
|
||||
return rows;
|
||||
}
|
||||
|
||||
private static (string Origin, string BasketId, string Basket, string Exit) Classify(long positionId, DateTime openedUtc, Dictionary<long, OrderRecord> byPosition, Dictionary<string, BasketOutcomeRow> byBasketId, IReadOnlyList<BasketOutcomeRow> baskets)
|
||||
{
|
||||
if (byPosition.TryGetValue(positionId, out OrderRecord? o))
|
||||
{
|
||||
if (o.BasketId.Length > 0 && byBasketId.TryGetValue(o.BasketId, out BasketOutcomeRow? b))
|
||||
{
|
||||
bool lone = b.ExitReason is "leg_risk_unwind" or "orphan_closed" or "bonifica_orfana" || !double.IsFinite(b.EntryZ);
|
||||
return (lone ? "orfana-bot" : "basket", o.BasketId, o.Basket, b.ExitReason);
|
||||
}
|
||||
|
||||
return ("orfana-bot", o.BasketId, o.Basket, string.Empty);
|
||||
}
|
||||
|
||||
// Before orders.jsonl existed (4.0.0) the only trace is a lone-leg row in baskets.csv whose motivation carries the position id.
|
||||
foreach (BasketOutcomeRow b in baskets)
|
||||
{
|
||||
if (b.Motivazione.Contains(positionId.ToString(CultureInfo.InvariantCulture), StringComparison.Ordinal))
|
||||
{
|
||||
return ("orfana-bot", b.BasketId, b.Basket, b.ExitReason);
|
||||
}
|
||||
}
|
||||
|
||||
return ("esterna", string.Empty, string.Empty, string.Empty);
|
||||
}
|
||||
|
||||
/// <summary>The standard periods of the Storico page, computed on the closed positions of the bot (cash movements apart).</summary>
|
||||
public static List<PeriodStats> Periods(IReadOnlyList<PositionRecord> positions, DateTime nowUtc, (DateTime From, DateTime To)? custom = null)
|
||||
{
|
||||
|
||||
@@ -0,0 +1,219 @@
|
||||
using System.Globalization;
|
||||
using System.Text.Json;
|
||||
|
||||
namespace Encelado.Core.Baskets.History;
|
||||
|
||||
/// <summary>
|
||||
/// One <c>correzione</c> line of <c>decisions.jsonl</c> with <c>tipo = pnl_realizzato</c>:
|
||||
/// the realised result of one row of <c>baskets.csv</c>, established from the venue's
|
||||
/// history, or the admission that it could not be (<see cref="Verified"/> false). The row
|
||||
/// itself is never edited; the corrected reader applies the newest line for its key.
|
||||
/// </summary>
|
||||
public sealed record PnlCorrectionRecord(DateTime Ts, string RowKey, double PnlGrossUsd, double PnlNetUsd, bool Verified)
|
||||
{
|
||||
public const string Evento = "correzione";
|
||||
|
||||
public const string Kind = "pnl_realizzato";
|
||||
|
||||
/// <summary>The key of a row: basket id and closing time (round-trip format), so lone legs with an empty basket id are told apart too.</summary>
|
||||
public static string KeyOf(BasketOutcomeRow row)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(row);
|
||||
return row.BasketId + "|" + Utc(row.ClosedUtc).ToString("O", CultureInfo.InvariantCulture);
|
||||
}
|
||||
|
||||
/// <summary>Reads a ledger line; null when it is not a P&L correction (or is damaged).</summary>
|
||||
public static PnlCorrectionRecord? TryParse(string line)
|
||||
{
|
||||
if (string.IsNullOrEmpty(line) || !line.Contains(Kind, StringComparison.Ordinal))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(line);
|
||||
JsonElement r = doc.RootElement;
|
||||
if (Str(r, "evento") != Evento || Str(r, "tipo") != Kind)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
string key = Str(r, "riga");
|
||||
if (key.Length == 0)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
bool verified = r.TryGetProperty("verificata", out JsonElement v) && v.ValueKind == JsonValueKind.True;
|
||||
return new PnlCorrectionRecord(LedgerTime(r, "ts"), key, Num(r, "pnl_gross_corretto"), Num(r, "pnl_net_corretto"), verified);
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
internal static DateTime Utc(DateTime t) => t.Kind switch
|
||||
{
|
||||
DateTimeKind.Local => t.ToUniversalTime(),
|
||||
DateTimeKind.Unspecified => DateTime.SpecifyKind(t, DateTimeKind.Utc),
|
||||
_ => t,
|
||||
};
|
||||
|
||||
internal static string Str(JsonElement e, string name) =>
|
||||
e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.String ? v.GetString() ?? string.Empty : string.Empty;
|
||||
|
||||
internal static double Num(JsonElement e, string name) =>
|
||||
e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.Number ? v.GetDouble() : double.NaN;
|
||||
|
||||
internal static DateTime LedgerTime(JsonElement e, string name) =>
|
||||
DateTime.TryParse(Str(e, name), CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out DateTime t) ? t : default;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The corrected reading of <c>baskets.csv</c>: the file never changes; the newest P&L
|
||||
/// correction of each row is applied on the way out, and a row whose P&L the venue could
|
||||
/// not confirm — an unverified correction, or an estimate written after the settlement
|
||||
/// timeout (<c>P&L: stima</c> in the motivation) — is marked <see cref="BasketOutcomeRow.Unverified"/>:
|
||||
/// it has no label, teaches nothing and is left out of the sums.
|
||||
/// </summary>
|
||||
public static class BasketCorrections
|
||||
{
|
||||
/// <summary>The words the settlement writes in the motivation of a row whose P&L is an estimate.</summary>
|
||||
public const string EstimateMarker = "P&L: stima";
|
||||
|
||||
/// <summary>The words of a row settled on the venue's history.</summary>
|
||||
public const string VenueMarker = "P&L: storico eToro";
|
||||
|
||||
public static List<BasketOutcomeRow> Apply(IReadOnlyList<BasketOutcomeRow> rows, IEnumerable<PnlCorrectionRecord> corrections)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
Dictionary<string, PnlCorrectionRecord> newest = Newest(corrections);
|
||||
List<BasketOutcomeRow> result = new(rows.Count);
|
||||
foreach (BasketOutcomeRow r in rows)
|
||||
{
|
||||
if (newest.TryGetValue(PnlCorrectionRecord.KeyOf(r), out PnlCorrectionRecord? c))
|
||||
{
|
||||
result.Add(c.Verified && double.IsFinite(c.PnlNetUsd)
|
||||
? r with { PnlGrossUsd = double.IsFinite(c.PnlGrossUsd) ? c.PnlGrossUsd : c.PnlNetUsd, PnlNetUsd = c.PnlNetUsd, Corrected = true, Unverified = false }
|
||||
: r with { PnlNetUsd = double.NaN, PnlGrossUsd = double.NaN, Corrected = true, Unverified = true });
|
||||
}
|
||||
else if (r.Motivazione.Contains(EstimateMarker, StringComparison.Ordinal) || !double.IsFinite(r.PnlNetUsd))
|
||||
{
|
||||
result.Add(r with { Unverified = true });
|
||||
}
|
||||
else
|
||||
{
|
||||
result.Add(r);
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/// <summary>The newest correction of every row key.</summary>
|
||||
public static Dictionary<string, PnlCorrectionRecord> Newest(IEnumerable<PnlCorrectionRecord> corrections)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(corrections);
|
||||
Dictionary<string, PnlCorrectionRecord> newest = new(StringComparer.Ordinal);
|
||||
foreach (PnlCorrectionRecord c in corrections.OrderBy(static c => c.Ts))
|
||||
{
|
||||
newest[c.RowKey] = c;
|
||||
}
|
||||
|
||||
return newest;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The one-off <c>correzione</c> lines that are not about a single row: an unreliable feature, the range of notes whose P&L fields are proceeds.</summary>
|
||||
public static class LedgerMarkers
|
||||
{
|
||||
public const string FeatureUnreliable = "feature_inaffidabile";
|
||||
|
||||
public const string ProceedsNotes = "pnl_note_proceeds";
|
||||
|
||||
public const string BackfillEvento = "verifica_realizzato";
|
||||
|
||||
/// <summary>Reads a <c>feature_inaffidabile</c> line: the feature and the time until which it is unreliable.</summary>
|
||||
public static bool TryParseFeatureMask(string line, out string feature, out DateTime untilUtc)
|
||||
{
|
||||
feature = string.Empty;
|
||||
untilUtc = default;
|
||||
if (string.IsNullOrEmpty(line) || !line.Contains(FeatureUnreliable, StringComparison.Ordinal))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(line);
|
||||
JsonElement r = doc.RootElement;
|
||||
if (PnlCorrectionRecord.Str(r, "evento") != PnlCorrectionRecord.Evento || PnlCorrectionRecord.Str(r, "tipo") != FeatureUnreliable)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
feature = PnlCorrectionRecord.Str(r, "feature");
|
||||
untilUtc = PnlCorrectionRecord.LedgerTime(r, "fino_a");
|
||||
return feature.Length > 0 && untilUtc != default;
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>True for a <c>correzione</c> line of the given <c>tipo</c>.</summary>
|
||||
public static bool IsCorrectionOfKind(string line, string kind)
|
||||
{
|
||||
if (string.IsNullOrEmpty(line) || !line.Contains(kind, StringComparison.Ordinal))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(line);
|
||||
JsonElement r = doc.RootElement;
|
||||
return PnlCorrectionRecord.Str(r, "evento") == PnlCorrectionRecord.Evento && PnlCorrectionRecord.Str(r, "tipo") == kind;
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Reads a <c>verifica_realizzato</c> line: the closing time of the last row it checked and the
|
||||
/// account it checked (<c>mode</c>; empty in the lines written before the 5.1 review, which said
|
||||
/// neither).
|
||||
/// </summary>
|
||||
public static bool TryParseBackfill(string line, out DateTime untilUtc, out string mode)
|
||||
{
|
||||
untilUtc = default;
|
||||
mode = string.Empty;
|
||||
if (string.IsNullOrEmpty(line) || !line.Contains(BackfillEvento, StringComparison.Ordinal))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(line);
|
||||
JsonElement r = doc.RootElement;
|
||||
if (PnlCorrectionRecord.Str(r, "evento") != BackfillEvento)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
untilUtc = PnlCorrectionRecord.LedgerTime(r, "fino_a");
|
||||
mode = PnlCorrectionRecord.Str(r, "mode");
|
||||
return untilUtc != default;
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,404 @@
|
||||
using System.Globalization;
|
||||
using System.Text.RegularExpressions;
|
||||
using Encelado.Core.Broker;
|
||||
|
||||
namespace Encelado.Core.Baskets.History;
|
||||
|
||||
/// <summary>A <c>leg_risk_unwind</c> or <c>orfana_chiusa</c> note of <c>decisions.jsonl</c> that names the position it closed.</summary>
|
||||
public sealed record LoneLegNote(DateTime Ts, string Evento, string BasketId, long PositionId, string Symbol, string ExitReason);
|
||||
|
||||
/// <summary>The fill prices of a basket's two legs as its <c>ingresso</c> line wrote them (<c>eseguito: A @ …, B @ …</c>).</summary>
|
||||
public sealed record EntryFill(string BasketId, DateTime Ts, double PriceA, double PriceB);
|
||||
|
||||
/// <summary>
|
||||
/// Which eToro positions a row of <c>baskets.csv</c> accounts for, from the bot's own files
|
||||
/// only — so its realised result can be looked up in the venue's history by position id.
|
||||
/// <list type="bullet">
|
||||
/// <item>A row written from 5.1 names its positions in the motivation (<c>| posizioni: …</c>).</item>
|
||||
/// <item>A basket: every filled order of <c>orders.jsonl</c> for its basket id on legs A, B
|
||||
/// and adds — except an add that was unwound at once (an <c>Unwind</c> order on the same
|
||||
/// position, or, in older lines without the position, the <c>leg_risk_unwind dell'aggiunta</c>
|
||||
/// of the same symbol within two minutes). Before <c>orders.jsonl</c> (4.0.x): the two fill
|
||||
/// prices of its <c>ingresso</c> line matched on the history (same instrument, side and
|
||||
/// opening rate, opened and closed at the row's times), when the basket had no adds.</item>
|
||||
/// <item>A lone leg: the note that closed it (same basket id, exit reason and symbol, within
|
||||
/// two minutes; each note serves one row, rows and notes paired in time order); else leg A
|
||||
/// of its basket id; else its motivation (<c>gamba singola …</c>) matched on the history by
|
||||
/// instrument, side, units and rates.</item>
|
||||
/// </list>
|
||||
/// Nothing is guessed: when a step is ambiguous the row stays without positions and its
|
||||
/// P&L is declared unverifiable.
|
||||
/// </summary>
|
||||
public sealed partial class PositionMap
|
||||
{
|
||||
private static readonly TimeSpan NoteWindow = TimeSpan.FromSeconds(120);
|
||||
private static readonly TimeSpan AddUnwindWindow = TimeSpan.FromSeconds(120);
|
||||
|
||||
private readonly Dictionary<string, List<(OrderRecord Last, DateTime SentUtc)>> _byBasket = new(StringComparer.Ordinal);
|
||||
private readonly List<LoneLegNote> _notes;
|
||||
private readonly Dictionary<string, EntryFill> _fills = new(StringComparer.Ordinal);
|
||||
|
||||
/// <summary>The note each lone row given to <see cref="Build"/> was paired with (an index of <see cref="_notes"/>), by row key; −1 when the pairing is ambiguous.</summary>
|
||||
private readonly Dictionary<string, int> _noteOfRow = new(StringComparer.Ordinal);
|
||||
|
||||
/// <summary>The notes already paired with a row: a note closes one position, so it serves one row.</summary>
|
||||
private readonly HashSet<int> _usedNotes = [];
|
||||
|
||||
private PositionMap(List<LoneLegNote> notes)
|
||||
{
|
||||
_notes = notes;
|
||||
}
|
||||
|
||||
/// <param name="orders">Every line of <c>orders.jsonl</c>.</param>
|
||||
/// <param name="notes">The notes that name a lone leg the bot closed.</param>
|
||||
/// <param name="fills">The fill prices of the <c>ingresso</c> lines.</param>
|
||||
/// <param name="rows">
|
||||
/// Every row of <c>baskets.csv</c>: the lone legs without positions are paired with the notes
|
||||
/// once, all together (5.1 review), so two rows can never take the same note. A row asked
|
||||
/// about without having been given here takes a note no other row took, if exactly one fits.
|
||||
/// </param>
|
||||
public static PositionMap Build(IReadOnlyList<OrderRecord> orders, IReadOnlyList<LoneLegNote> notes, IReadOnlyList<EntryFill> fills, IReadOnlyList<BasketOutcomeRow>? rows = null)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(orders);
|
||||
ArgumentNullException.ThrowIfNull(notes);
|
||||
ArgumentNullException.ThrowIfNull(fills);
|
||||
PositionMap map = new([.. notes]);
|
||||
|
||||
// The last line of every order is its state; the first says when it was sent.
|
||||
Dictionary<string, OrderRecord> last = new(StringComparer.Ordinal);
|
||||
Dictionary<string, DateTime> sent = new(StringComparer.Ordinal);
|
||||
foreach (OrderRecord o in orders)
|
||||
{
|
||||
if (o.ClientRef.Length == 0)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
sent.TryAdd(o.ClientRef, o.Ts);
|
||||
last[o.ClientRef] = o;
|
||||
}
|
||||
|
||||
foreach ((string clientRef, OrderRecord o) in last)
|
||||
{
|
||||
if (o.BasketId.Length == 0)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!map._byBasket.TryGetValue(o.BasketId, out List<(OrderRecord, DateTime)>? list))
|
||||
{
|
||||
list = [];
|
||||
map._byBasket[o.BasketId] = list;
|
||||
}
|
||||
|
||||
list.Add((o, sent[clientRef]));
|
||||
}
|
||||
|
||||
foreach (EntryFill f in fills)
|
||||
{
|
||||
if (f.BasketId.Length > 0)
|
||||
{
|
||||
map._fills[f.BasketId] = f;
|
||||
}
|
||||
}
|
||||
|
||||
map.PairNotes(rows ?? []);
|
||||
return map;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Pairs the lone rows without positions with the notes that may have closed them. A row and
|
||||
/// a note are candidates when they share basket id (an empty one only with an empty one),
|
||||
/// exit reason and symbol and are at most two minutes apart. Candidates form groups (rows
|
||||
/// and notes linked by a candidacy, directly or through others); a group is paired only when
|
||||
/// it has as many notes as rows and the rows in closing order match the notes in time order
|
||||
/// one by one (each close wrote its note right after it). Any other group is ambiguous: its
|
||||
/// rows get no position from a note.
|
||||
/// </summary>
|
||||
private void PairNotes(IReadOnlyList<BasketOutcomeRow> rows)
|
||||
{
|
||||
List<BasketOutcomeRow> lone = [.. rows.Where(static r => r.IsLoneLeg && NamedPositions(r.Motivazione).Count == 0).OrderBy(static r => r.ClosedUtc)];
|
||||
if (lone.Count == 0 || _notes.Count == 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
// Union-find over rows (0..n-1) and notes (n..n+m-1).
|
||||
int n = lone.Count;
|
||||
int[] parent = [.. Enumerable.Range(0, n + _notes.Count)];
|
||||
List<int>[] candidates = new List<int>[n];
|
||||
for (int i = 0; i < n; i++)
|
||||
{
|
||||
candidates[i] = Candidates(lone[i], static _ => true);
|
||||
foreach (int j in candidates[i])
|
||||
{
|
||||
parent[Find(i)] = Find(n + j);
|
||||
}
|
||||
}
|
||||
|
||||
Dictionary<int, (List<int> Rows, SortedSet<int> Notes)> groups = [];
|
||||
for (int i = 0; i < n; i++)
|
||||
{
|
||||
if (candidates[i].Count == 0)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
int root = Find(i);
|
||||
if (!groups.TryGetValue(root, out (List<int> Rows, SortedSet<int> Notes) g))
|
||||
{
|
||||
g = ([], []);
|
||||
groups[root] = g;
|
||||
}
|
||||
|
||||
g.Rows.Add(i);
|
||||
g.Notes.UnionWith(candidates[i]);
|
||||
}
|
||||
|
||||
foreach ((List<int> groupRows, SortedSet<int> groupNotes) in groups.Values)
|
||||
{
|
||||
// Rows are already in closing order; the notes go in time order.
|
||||
List<int> notes = [.. groupNotes.OrderBy(j => _notes[j].Ts)];
|
||||
bool paired = notes.Count == groupRows.Count && groupRows.Select((r, k) => candidates[r].Contains(notes[k])).All(static ok => ok);
|
||||
for (int k = 0; k < groupRows.Count; k++)
|
||||
{
|
||||
_noteOfRow[PnlCorrectionRecord.KeyOf(lone[groupRows[k]])] = paired ? notes[k] : -1;
|
||||
if (paired)
|
||||
{
|
||||
_usedNotes.Add(notes[k]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
int Find(int x)
|
||||
{
|
||||
while (parent[x] != x)
|
||||
{
|
||||
parent[x] = parent[parent[x]];
|
||||
x = parent[x];
|
||||
}
|
||||
|
||||
return x;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The notes (indexes) that may have closed a lone row: same basket id, exit reason and symbol, within the window.</summary>
|
||||
private List<int> Candidates(BasketOutcomeRow row, Func<int, bool> available)
|
||||
{
|
||||
Match described = LoneRegex().Match(row.Motivazione);
|
||||
string symbol = described.Success ? described.Groups[3].Value : string.Empty;
|
||||
List<int> found = [];
|
||||
for (int j = 0; j < _notes.Count; j++)
|
||||
{
|
||||
LoneLegNote n = _notes[j];
|
||||
if (n.PositionId > 0 && available(j) && n.BasketId.Equals(row.BasketId, StringComparison.Ordinal) &&
|
||||
(n.ExitReason.Length == 0 || n.ExitReason == row.ExitReason) &&
|
||||
(n.Symbol.Length == 0 || symbol.Length == 0 || n.Symbol.Equals(symbol, StringComparison.OrdinalIgnoreCase)) &&
|
||||
(n.Ts - row.ClosedUtc).Duration() <= NoteWindow)
|
||||
{
|
||||
found.Add(j);
|
||||
}
|
||||
}
|
||||
|
||||
return found;
|
||||
}
|
||||
|
||||
/// <summary>The positions of <paramref name="row"/>; empty when the bot's files cannot establish them without guessing.</summary>
|
||||
public IReadOnlyList<long> IdsOf(BasketOutcomeRow row, IReadOnlyList<ClosedTrade> history, Func<string, long> instrumentOf)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(row);
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
ArgumentNullException.ThrowIfNull(instrumentOf);
|
||||
|
||||
List<long> named = NamedPositions(row.Motivazione);
|
||||
if (named.Count > 0)
|
||||
{
|
||||
return named;
|
||||
}
|
||||
|
||||
return row.IsLoneLeg ? LoneLeg(row, history, instrumentOf) : Basket(row, history, instrumentOf);
|
||||
}
|
||||
|
||||
/// <summary>The ids a motivation names after <c>posizioni:</c> (rows written from 5.1).</summary>
|
||||
public static List<long> NamedPositions(string motivazione)
|
||||
{
|
||||
List<long> ids = [];
|
||||
if (string.IsNullOrEmpty(motivazione))
|
||||
{
|
||||
return ids;
|
||||
}
|
||||
|
||||
foreach (Match m in NamedRegex().Matches(motivazione))
|
||||
{
|
||||
foreach (string part in m.Groups[1].Value.Split([' ', ','], StringSplitOptions.RemoveEmptyEntries))
|
||||
{
|
||||
if (long.TryParse(part, NumberStyles.Integer, CultureInfo.InvariantCulture, out long id) && id > 0 && !ids.Contains(id))
|
||||
{
|
||||
ids.Add(id);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return ids;
|
||||
}
|
||||
|
||||
/// <summary>The marker a row's motivation carries so its positions can be found again: <c>posizioni: 1 2 3</c>.</summary>
|
||||
public static string Mark(IEnumerable<long> ids)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(ids);
|
||||
return "posizioni: " + string.Join(' ', ids.Where(static i => i > 0).Distinct().Select(static i => i.ToString(CultureInfo.InvariantCulture)));
|
||||
}
|
||||
|
||||
private List<long> Basket(BasketOutcomeRow row, IReadOnlyList<ClosedTrade> history, Func<string, long> instrumentOf)
|
||||
{
|
||||
List<long> ids = [];
|
||||
if (row.BasketId.Length > 0 && _byBasket.TryGetValue(row.BasketId, out List<(OrderRecord Last, DateTime SentUtc)>? orders))
|
||||
{
|
||||
List<(OrderRecord Last, DateTime SentUtc)> unwinds = [.. orders.Where(static o => o.Last.Leg == OrderLeg.Unwind)];
|
||||
foreach ((OrderRecord o, DateTime sentUtc) in orders)
|
||||
{
|
||||
if (o.Leg is not (OrderLeg.A or OrderLeg.B or OrderLeg.Add) || o.Resolution != OrderResolution.Filled || o.PositionId <= 0)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (o.Leg == OrderLeg.Add && IsUnwound(o, sentUtc, unwinds))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
if (!ids.Contains(o.PositionId))
|
||||
{
|
||||
ids.Add(o.PositionId);
|
||||
}
|
||||
}
|
||||
|
||||
if (ids.Count > 0)
|
||||
{
|
||||
return ids;
|
||||
}
|
||||
}
|
||||
|
||||
// 4.0.x: no order register. The fill prices of the ingresso line, only without adds
|
||||
// (the adds' positions are not written anywhere) and only when unambiguous.
|
||||
if (row.Adds > 0 || !_fills.TryGetValue(row.BasketId, out EntryFill? fill))
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
string[] pair = row.Basket.Split('/');
|
||||
if (pair.Length != 2 || !SyntheticCross.TryDerive(pair[0], pair[1], out SyntheticCross? cross) || cross is null)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
(bool buyA, bool buyB) = cross.Legs(row.BuyCross);
|
||||
long a = Unique(history, instrumentOf(pair[0]), buyA, fill.PriceA, row);
|
||||
long b = Unique(history, instrumentOf(pair[1]), buyB, fill.PriceB, row);
|
||||
return a > 0 && b > 0 && a != b ? [a, b] : [];
|
||||
}
|
||||
|
||||
private static bool IsUnwound(OrderRecord add, DateTime addSentUtc, List<(OrderRecord Last, DateTime SentUtc)> unwinds)
|
||||
{
|
||||
foreach ((OrderRecord u, DateTime sentUtc) in unwinds)
|
||||
{
|
||||
if (u.PositionId > 0)
|
||||
{
|
||||
if (u.PositionId == add.PositionId)
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
// Lines written before 5.1 carry no position on the unwind: the add of the same
|
||||
// symbol undone within two minutes by the "leg_risk_unwind dell'aggiunta".
|
||||
if (u.Symbol.Equals(add.Symbol, StringComparison.OrdinalIgnoreCase) &&
|
||||
u.Motivazione.Contains("aggiunta", StringComparison.OrdinalIgnoreCase) &&
|
||||
sentUtc >= addSentUtc && sentUtc - addSentUtc <= AddUnwindWindow)
|
||||
{
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
private static long Unique(IReadOnlyList<ClosedTrade> history, long instrumentId, bool isBuy, double openRate, BasketOutcomeRow row)
|
||||
{
|
||||
if (instrumentId <= 0 || !(openRate > 0))
|
||||
{
|
||||
return 0;
|
||||
}
|
||||
|
||||
List<ClosedTrade> hits = [.. history.Where(t => t.InstrumentId == instrumentId && t.IsBuy == isBuy && Near(t.OpenRate, openRate) &&
|
||||
(t.OpenedUtc - row.OpenedUtc).Duration() <= TimeSpan.FromMinutes(10) && (t.ClosedUtc - row.ClosedUtc).Duration() <= TimeSpan.FromMinutes(15))];
|
||||
return hits.Count == 1 ? hits[0].PositionId : 0;
|
||||
}
|
||||
|
||||
private List<long> LoneLeg(BasketOutcomeRow row, IReadOnlyList<ClosedTrade> history, Func<string, long> instrumentOf)
|
||||
{
|
||||
Match described = LoneRegex().Match(row.Motivazione);
|
||||
string symbol = described.Success ? described.Groups[3].Value : string.Empty;
|
||||
|
||||
// 1. The note written when the leg was closed: the one paired with the row, or — for a row
|
||||
// not given to Build — the only note no other row took. Two candidates: nothing is guessed.
|
||||
if (_noteOfRow.TryGetValue(PnlCorrectionRecord.KeyOf(row), out int paired))
|
||||
{
|
||||
return paired >= 0 ? [_notes[paired].PositionId] : [];
|
||||
}
|
||||
|
||||
List<int> free = Candidates(row, j => !_usedNotes.Contains(j));
|
||||
if (free.Count > 1)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
if (free.Count == 1)
|
||||
{
|
||||
_usedNotes.Add(free[0]);
|
||||
_noteOfRow[PnlCorrectionRecord.KeyOf(row)] = free[0];
|
||||
return [_notes[free[0]].PositionId];
|
||||
}
|
||||
|
||||
// 2. Leg A of the basket attempt it belonged to (a pending entry unwound).
|
||||
if (row.BasketId.Length > 0 && _byBasket.TryGetValue(row.BasketId, out List<(OrderRecord Last, DateTime SentUtc)>? orders))
|
||||
{
|
||||
List<long> legA = [.. orders.Where(static o => o.Last.Leg == OrderLeg.A && o.Last.Resolution == OrderResolution.Filled && o.Last.PositionId > 0)
|
||||
.Select(static o => o.Last.PositionId).Distinct()];
|
||||
if (legA.Count == 1)
|
||||
{
|
||||
return legA;
|
||||
}
|
||||
}
|
||||
|
||||
// 3. What the motivation says: instrument, side, units, entry and exit rate.
|
||||
if (!described.Success)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
bool isBuy = described.Groups[1].Value == "long";
|
||||
double units = double.Parse(described.Groups[2].Value, CultureInfo.InvariantCulture);
|
||||
double entry = double.Parse(described.Groups[4].Value, CultureInfo.InvariantCulture);
|
||||
double exit = double.Parse(described.Groups[5].Value, CultureInfo.InvariantCulture);
|
||||
long instrumentId = instrumentOf(symbol);
|
||||
if (instrumentId <= 0)
|
||||
{
|
||||
return [];
|
||||
}
|
||||
|
||||
List<ClosedTrade> hits = [.. history.Where(t => t.InstrumentId == instrumentId && t.IsBuy == isBuy && Math.Abs(t.Units - units) <= 0.01 &&
|
||||
Near(t.OpenRate, entry) && (exit <= 0 || Near(t.CloseRate, exit)) && (t.ClosedUtc - row.ClosedUtc).Duration() <= TimeSpan.FromDays(1))];
|
||||
return hits.Count == 1 ? [hits[0].PositionId] : [];
|
||||
}
|
||||
|
||||
private static bool Near(double a, double b) => Math.Abs(a - b) <= 1e-6 * Math.Max(1, Math.Abs(b));
|
||||
|
||||
[GeneratedRegex(@"posizioni: ([0-9][0-9 ,]*)", RegexOptions.CultureInvariant)]
|
||||
private static partial Regex NamedRegex();
|
||||
|
||||
[GeneratedRegex(@"gamba singola (long|short) ([0-9]+(?:\.[0-9]+)?) ([A-Z]{6}) @ ([0-9]+(?:\.[0-9]+)?) chiusa @ ([0-9]+(?:\.[0-9]+)?)", RegexOptions.CultureInvariant)]
|
||||
private static partial Regex LoneRegex();
|
||||
}
|
||||
@@ -0,0 +1,133 @@
|
||||
using System.Globalization;
|
||||
|
||||
namespace Encelado.Core.Baskets.History;
|
||||
|
||||
/// <summary>Whose a position is, as the Storico page tells it: <c>basket</c>, <c>orfana-bot</c> or <c>esterna</c>.</summary>
|
||||
public readonly record struct PositionOwner(string Origin, string BasketId, string Basket, string ExitReason)
|
||||
{
|
||||
public const string BasketOrigin = "basket";
|
||||
|
||||
public const string OrphanOrigin = "orfana-bot";
|
||||
|
||||
public const string ForeignOrigin = "esterna";
|
||||
|
||||
public static readonly PositionOwner Foreign = new(ForeignOrigin, string.Empty, string.Empty, string.Empty);
|
||||
|
||||
/// <summary>A position of the bot: a basket leg or a lone leg of its own.</summary>
|
||||
public bool IsBot => Origin is BasketOrigin or OrphanOrigin;
|
||||
|
||||
/// <summary>The unit a win or a loss is counted on: the basket instance for its legs, the position itself for a lone leg.</summary>
|
||||
public string UnitKey(long positionId) =>
|
||||
Origin == BasketOrigin && BasketId.Length > 0 ? BasketId : "#" + positionId.ToString(CultureInfo.InvariantCulture);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The one rule that says whose a position is, shared by the Storico page and by the
|
||||
/// engine's "P&L oggi" so the two can never disagree. A position is the bot's when an
|
||||
/// order line of <c>orders.jsonl</c> produced it (legs A, B and adds, never the closes);
|
||||
/// it is a basket leg when that basket instance has a row in <c>baskets.csv</c> that is not
|
||||
/// a lone leg, a lone leg (<c>orfana-bot</c>) otherwise. Before <c>orders.jsonl</c> existed
|
||||
/// the only trace is a row of <c>baskets.csv</c> whose motivation carries the position id.
|
||||
/// Everything else is <c>esterna</c>. Pure: fed with the ledger's lines, no I/O.
|
||||
/// </summary>
|
||||
public sealed class PositionOrigins
|
||||
{
|
||||
private readonly Dictionary<long, OrderRecord> _byPosition = [];
|
||||
private readonly Dictionary<string, BasketOutcomeRow> _byBasketId = new(StringComparer.Ordinal);
|
||||
private readonly List<BasketOutcomeRow> _rows = [];
|
||||
|
||||
/// <summary>The positions a lone-leg row names (<c>posizioni: …</c>, from 5.1): that row is theirs, whatever the basket instance it carries.</summary>
|
||||
private readonly Dictionary<long, BasketOutcomeRow> _loneByPosition = [];
|
||||
|
||||
public PositionOrigins()
|
||||
{
|
||||
}
|
||||
|
||||
public PositionOrigins(IEnumerable<OrderRecord> orders, IEnumerable<BasketOutcomeRow> baskets)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(orders);
|
||||
ArgumentNullException.ThrowIfNull(baskets);
|
||||
foreach (OrderRecord o in orders)
|
||||
{
|
||||
Add(o);
|
||||
}
|
||||
|
||||
foreach (BasketOutcomeRow b in baskets)
|
||||
{
|
||||
Add(b);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>An order line: the last line that produced a position id says whose it is.</summary>
|
||||
public void Add(OrderRecord order)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(order);
|
||||
if (order.PositionId > 0 && order.Leg is not (OrderLeg.Close or OrderLeg.Unwind))
|
||||
{
|
||||
_byPosition[order.PositionId] = order;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A row of <c>baskets.csv</c>: the last row of a basket instance gives its exit reason, but
|
||||
/// a lone leg never takes the place of the basket's own row (5.1 review). An add undone at
|
||||
/// once carries the instance of the open basket and, sorted by opening time, comes after the
|
||||
/// basket's row: it would turn every leg of that basket into an orphan.
|
||||
/// </summary>
|
||||
public void Add(BasketOutcomeRow row)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(row);
|
||||
_rows.Add(row);
|
||||
bool lone = IsLone(row);
|
||||
if (row.BasketId.Length > 0 && (!lone || !_byBasketId.TryGetValue(row.BasketId, out BasketOutcomeRow? before) || IsLone(before)))
|
||||
{
|
||||
_byBasketId[row.BasketId] = row;
|
||||
}
|
||||
|
||||
if (lone)
|
||||
{
|
||||
foreach (long id in PositionMap.NamedPositions(row.Motivazione))
|
||||
{
|
||||
_loneByPosition[id] = row;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>A row of a lone leg (an unwind, an orphan, the bonifica): no entry z.</summary>
|
||||
private static bool IsLone(BasketOutcomeRow row) => row.ExitReason is "leg_risk_unwind" or "orphan_closed" or "bonifica_orfana" || !double.IsFinite(row.EntryZ);
|
||||
|
||||
public PositionOwner Classify(long positionId)
|
||||
{
|
||||
// A position a lone-leg row names is that lone leg, even when the row carries the instance of a basket.
|
||||
if (_loneByPosition.TryGetValue(positionId, out BasketOutcomeRow? single))
|
||||
{
|
||||
string basket = _byPosition.TryGetValue(positionId, out OrderRecord? producer) && producer.Basket.Length > 0 ? producer.Basket : single.Basket;
|
||||
return new PositionOwner(PositionOwner.OrphanOrigin, single.BasketId, basket, single.ExitReason);
|
||||
}
|
||||
|
||||
if (_byPosition.TryGetValue(positionId, out OrderRecord? o))
|
||||
{
|
||||
if (o.BasketId.Length > 0 && _byBasketId.TryGetValue(o.BasketId, out BasketOutcomeRow? b))
|
||||
{
|
||||
return new PositionOwner(IsLone(b) ? PositionOwner.OrphanOrigin : PositionOwner.BasketOrigin, o.BasketId, o.Basket, b.ExitReason);
|
||||
}
|
||||
|
||||
return new PositionOwner(PositionOwner.OrphanOrigin, o.BasketId, o.Basket, string.Empty);
|
||||
}
|
||||
|
||||
// Before orders.jsonl existed (4.0.0), and for an orphan adopted without an order of
|
||||
// its own, the only trace is a lone-leg row whose motivation carries the position id.
|
||||
string id = positionId.ToString(CultureInfo.InvariantCulture);
|
||||
foreach (BasketOutcomeRow b in _rows)
|
||||
{
|
||||
if (b.Motivazione.Contains(id, StringComparison.Ordinal))
|
||||
{
|
||||
return new PositionOwner(PositionOwner.OrphanOrigin, b.BasketId, b.Basket, b.ExitReason);
|
||||
}
|
||||
}
|
||||
|
||||
return PositionOwner.Foreign;
|
||||
}
|
||||
|
||||
public bool IsBot(long positionId) => Classify(positionId).IsBot;
|
||||
}
|
||||
@@ -0,0 +1,219 @@
|
||||
using Encelado.Core.Broker;
|
||||
|
||||
namespace Encelado.Core.Baskets.History;
|
||||
|
||||
/// <summary>What the venue's history says about a set of positions: their result, or which of them it does not show yet.</summary>
|
||||
public sealed record Settlement(double NetUsd, double GrossUsd, double FeesUsd, IReadOnlyList<long> Missing)
|
||||
{
|
||||
/// <summary>Every position was found: <see cref="NetUsd"/> is the P&L of record (zero is a result, not "unknown").</summary>
|
||||
public bool Complete => Missing.Count == 0;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The realised result of closed positions. The P&L of record is the venue's trade
|
||||
/// history joined by position id: <c>netProfit − fees</c>. The only other number is a
|
||||
/// provisional estimate from the close prices, used until the history confirms.
|
||||
/// </summary>
|
||||
public static class RealizedSettlement
|
||||
{
|
||||
public static Settlement Of(IEnumerable<long> ids, IReadOnlyList<ClosedTrade> history)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(ids);
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
Dictionary<long, ClosedTrade> byId = [];
|
||||
foreach (ClosedTrade t in history)
|
||||
{
|
||||
byId[t.PositionId] = t;
|
||||
}
|
||||
|
||||
double gross = 0, fees = 0;
|
||||
List<long> missing = [];
|
||||
foreach (long id in ids.Distinct())
|
||||
{
|
||||
if (byId.TryGetValue(id, out ClosedTrade? t))
|
||||
{
|
||||
gross += t.NetProfit;
|
||||
fees += t.Fees;
|
||||
}
|
||||
else
|
||||
{
|
||||
missing.Add(id);
|
||||
}
|
||||
}
|
||||
|
||||
return new Settlement(gross - fees, gross, fees, missing);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// eToro's netProfit as it computes it — units × Δrate × (quote → USD) — minus the fees:
|
||||
/// matches the history to the cent on NZDUSD, EURNZD and USDCAD (2026-09-29). NaN when
|
||||
/// any input is missing: an estimate is never made up.
|
||||
/// </summary>
|
||||
public static double Estimate(bool isBuy, double units, double openRate, double closeRate, double conversionRate, double feesUsd) =>
|
||||
units > 0 && openRate > 0 && closeRate > 0 && double.IsFinite(conversionRate) && conversionRate > 0 && double.IsFinite(feesUsd)
|
||||
? ((isBuy ? closeRate - openRate : openRate - closeRate) * units * conversionRate) - feesUsd
|
||||
: double.NaN;
|
||||
}
|
||||
|
||||
/// <summary>The closed units of the day: baskets, lone legs, and how many ended above zero.</summary>
|
||||
public sealed record TodayClosedStats(int Baskets, int Won, int Lost, int LoneLegs)
|
||||
{
|
||||
public static readonly TodayClosedStats Empty = new(0, 0, 0, 0);
|
||||
}
|
||||
|
||||
|
||||
/// <summary>
|
||||
/// "P&L oggi": the realised net result (<c>netProfit − fees</c>) of the bot's positions
|
||||
/// — basket legs and lone legs, classified as the Storico page does — closed in the
|
||||
/// current UTC day, recomputed from the venue's history on every reading, plus the
|
||||
/// provisional estimates of closes the history does not show yet. It equals the Storico's
|
||||
/// "oggi" period by construction. Unknown (NaN) until the history of the day has been read
|
||||
/// once; reset at UTC midnight. Foreign positions, cash movements and the unrealised
|
||||
/// result never enter it. Pure: the engine feeds it from its own thread; what the other
|
||||
/// threads read is one immutable picture, replaced whole after every change.
|
||||
/// </summary>
|
||||
public sealed class RealizedToday
|
||||
{
|
||||
private sealed record View(double Settled, double ProvisionalSum, int ProvisionalCount, TodayClosedStats Closed);
|
||||
|
||||
private readonly Dictionary<string, (long[] Ids, double Estimate, bool Lone)> _provisional = new(StringComparer.Ordinal);
|
||||
private TodayClosedStats _settledStats = TodayClosedStats.Empty;
|
||||
private double _settled = double.NaN;
|
||||
private View _view = new(double.NaN, 0, 0, TodayClosedStats.Empty);
|
||||
|
||||
public DateOnly Day { get; private set; }
|
||||
|
||||
/// <summary>The day's result from the history alone; NaN before the first reading of the day.</summary>
|
||||
public double Settled => Volatile.Read(ref _view).Settled;
|
||||
|
||||
public bool IsKnown => double.IsFinite(Settled);
|
||||
|
||||
/// <summary>The settled result plus the estimates still waiting for the history; NaN while the day is unknown.</summary>
|
||||
public double Value
|
||||
{
|
||||
get
|
||||
{
|
||||
View v = Volatile.Read(ref _view);
|
||||
return double.IsFinite(v.Settled) ? v.Settled + v.ProvisionalSum : double.NaN;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>True while <see cref="Value"/> contains estimates the history has not confirmed yet.</summary>
|
||||
public bool IsProvisional => Volatile.Read(ref _view).ProvisionalCount > 0;
|
||||
|
||||
public int ProvisionalCount => Volatile.Read(ref _view).ProvisionalCount;
|
||||
|
||||
/// <summary>The day's closed units from the history, plus the provisional ones.</summary>
|
||||
public TodayClosedStats Closed => Volatile.Read(ref _view).Closed;
|
||||
|
||||
/// <summary>Moves to the day of <paramref name="nowUtc"/>; everything restarts unknown. True when the day changed.</summary>
|
||||
public bool Roll(DateTime nowUtc)
|
||||
{
|
||||
DateOnly d = DateOnly.FromDateTime(nowUtc);
|
||||
if (d == Day)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
Day = d;
|
||||
_settled = double.NaN;
|
||||
_settledStats = TodayClosedStats.Empty;
|
||||
_provisional.Clear();
|
||||
Publish();
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>A close the history does not show yet: its estimate counts until every one of its positions appears.</summary>
|
||||
public void AddProvisional(string key, IReadOnlyCollection<long> ids, double estimate, DateTime closedUtc, bool lone = false)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(key);
|
||||
ArgumentNullException.ThrowIfNull(ids);
|
||||
if (DateOnly.FromDateTime(closedUtc) == Day)
|
||||
{
|
||||
_provisional[key] = ([.. ids], estimate, lone);
|
||||
Publish();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Recomputes the day from a fresh reading of the history. A provisional close whose
|
||||
/// positions all appear is replaced by them, never added to them; while only some of
|
||||
/// them appear, those are held back and the estimate still stands for the whole close.
|
||||
/// </summary>
|
||||
public void Apply(IReadOnlyList<ClosedTrade> history, Func<long, PositionOwner> owner)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
ArgumentNullException.ThrowIfNull(owner);
|
||||
DateTime from = Day.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc);
|
||||
DateTime to = from.AddDays(1);
|
||||
HashSet<long> inHistory = [.. history.Select(static t => t.PositionId)];
|
||||
foreach (string k in _provisional.Where(p => p.Value.Ids.Length > 0 && p.Value.Ids.All(inHistory.Contains)).Select(static p => p.Key).ToList())
|
||||
{
|
||||
_provisional.Remove(k);
|
||||
}
|
||||
|
||||
HashSet<long> heldBack = [.. _provisional.Values.SelectMany(static p => p.Ids)];
|
||||
HashSet<long> seen = [];
|
||||
Dictionary<string, (double Net, bool Lone)> units = new(StringComparer.Ordinal);
|
||||
double sum = 0;
|
||||
foreach (ClosedTrade t in history)
|
||||
{
|
||||
if (t.ClosedUtc < from || t.ClosedUtc >= to || heldBack.Contains(t.PositionId) || !seen.Add(t.PositionId))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
PositionOwner o = owner(t.PositionId);
|
||||
if (!o.IsBot)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
sum += t.NetUsd;
|
||||
string key = o.UnitKey(t.PositionId);
|
||||
(double net, _) = units.GetValueOrDefault(key);
|
||||
units[key] = (net + t.NetUsd, o.Origin != PositionOwner.BasketOrigin || o.BasketId.Length == 0);
|
||||
}
|
||||
|
||||
_settled = sum;
|
||||
_settledStats = new TodayClosedStats(
|
||||
units.Values.Count(static u => !u.Lone),
|
||||
units.Values.Count(static u => u.Net > 0),
|
||||
units.Values.Count(static u => u.Net <= 0),
|
||||
units.Values.Count(static u => u.Lone));
|
||||
Publish();
|
||||
}
|
||||
|
||||
/// <summary>The picture the readers see: the settled part, the estimates, the units — replaced whole.</summary>
|
||||
private void Publish()
|
||||
{
|
||||
int baskets = _settledStats.Baskets, won = _settledStats.Won, lost = _settledStats.Lost, lone = _settledStats.LoneLegs;
|
||||
double provisional = 0;
|
||||
foreach ((_, double estimate, bool isLone) in _provisional.Values)
|
||||
{
|
||||
if (isLone)
|
||||
{
|
||||
lone++;
|
||||
}
|
||||
else
|
||||
{
|
||||
baskets++;
|
||||
}
|
||||
|
||||
if (double.IsFinite(estimate))
|
||||
{
|
||||
provisional += estimate;
|
||||
if (estimate > 0)
|
||||
{
|
||||
won++;
|
||||
}
|
||||
else
|
||||
{
|
||||
lost++;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Volatile.Write(ref _view, new View(_settled, provisional, _provisional.Count, new TodayClosedStats(baskets, won, lost, lone)));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,233 @@
|
||||
using System.Globalization;
|
||||
using System.Text.Json;
|
||||
using Encelado.Core.Broker;
|
||||
|
||||
namespace Encelado.Core.Baskets.History;
|
||||
|
||||
/// <summary>Where the P&L of a settled close came from.</summary>
|
||||
public enum SettlementSource
|
||||
{
|
||||
/// <summary>The venue's trade history: netProfit − fees of every position. The P&L of record.</summary>
|
||||
Venue = 0,
|
||||
|
||||
/// <summary>The estimate from the close prices, written when the history did not show the positions in time. Never teaches.</summary>
|
||||
Estimate,
|
||||
|
||||
/// <summary>A simulator's own final number (backtest).</summary>
|
||||
Simulator,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A close waiting for the venue's history: the <c>baskets.csv</c> row as it will be
|
||||
/// written (its P&L columns hold the estimate until then), the positions to look up,
|
||||
/// and what the learning needs at settlement time (the volatility context of the close,
|
||||
/// captured when it happened).
|
||||
/// </summary>
|
||||
public sealed record PendingSettlement(
|
||||
string Key,
|
||||
BasketOutcomeRow Row,
|
||||
long[] Ids,
|
||||
double Estimate,
|
||||
DateTime ClosedUtc,
|
||||
bool Learn,
|
||||
int VolContext,
|
||||
string Title,
|
||||
string Detail)
|
||||
{
|
||||
/// <summary>A lone leg (unwind, orphan): no entry z.</summary>
|
||||
public bool IsLoneLeg => Row.IsLoneLeg;
|
||||
|
||||
public void Write(Utf8JsonWriter w)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
w.WriteStartObject();
|
||||
w.WriteString("key", Key);
|
||||
w.WriteString("rowCsv", Row.ToCsv());
|
||||
w.WriteStartArray("ids");
|
||||
foreach (long id in Ids)
|
||||
{
|
||||
w.WriteNumberValue(id);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
if (double.IsFinite(Estimate))
|
||||
{
|
||||
w.WriteNumber("estimate", Estimate);
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("estimate");
|
||||
}
|
||||
|
||||
w.WriteString("closedUtc", ClosedUtc.ToString("O", CultureInfo.InvariantCulture));
|
||||
w.WriteBoolean("learn", Learn);
|
||||
w.WriteNumber("volContext", VolContext);
|
||||
w.WriteString("title", Title);
|
||||
w.WriteString("detail", Detail);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
/// <summary>Reads one item of <c>pendingSettlements</c>; null when it is damaged.</summary>
|
||||
public static PendingSettlement? Read(JsonElement e)
|
||||
{
|
||||
try
|
||||
{
|
||||
string csv = PnlCorrectionRecord.Str(e, "rowCsv");
|
||||
if (BasketOutcomeRow.Parse(csv) is not { } row)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
List<long> ids = [];
|
||||
if (e.TryGetProperty("ids", out JsonElement arr) && arr.ValueKind == JsonValueKind.Array)
|
||||
{
|
||||
foreach (JsonElement x in arr.EnumerateArray())
|
||||
{
|
||||
if (x.ValueKind == JsonValueKind.Number && x.TryGetInt64(out long id) && id > 0)
|
||||
{
|
||||
ids.Add(id);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
DateTime closed = PnlCorrectionRecord.LedgerTime(e, "closedUtc");
|
||||
return new PendingSettlement(
|
||||
PnlCorrectionRecord.Str(e, "key"), row, [.. ids], PnlCorrectionRecord.Num(e, "estimate"),
|
||||
closed == default ? row.ClosedUtc : closed,
|
||||
e.TryGetProperty("learn", out JsonElement l) && l.ValueKind == JsonValueKind.True,
|
||||
e.TryGetProperty("volContext", out JsonElement v) && v.ValueKind == JsonValueKind.Number ? v.GetInt32() : 0,
|
||||
PnlCorrectionRecord.Str(e, "title"), PnlCorrectionRecord.Str(e, "detail"));
|
||||
}
|
||||
catch (Exception ex) when (ex is InvalidOperationException or FormatException)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>A close settled: the row to write, the numbers, where they came from.</summary>
|
||||
public sealed record SettledOutcome(PendingSettlement Pending, BasketOutcomeRow Row, double GrossUsd, double NetUsd, SettlementSource Source)
|
||||
{
|
||||
/// <summary>A final number (venue or simulator): the only kind that may teach the models.</summary>
|
||||
public bool IsFinal => Source != SettlementSource.Estimate;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The settlement queue (decision P2 of 5.1). A close is not a P&L until the venue's
|
||||
/// history shows its positions: then the row is written with <c>netProfit − fees</c>. A
|
||||
/// close the history does not show within <see cref="Timeout"/> is written with the
|
||||
/// estimate, flagged <c>P&L: stima</c>, and never teaches. The queue is part of the
|
||||
/// engine's state on disk (<c>pendingSettlements</c>), so a restart loses nothing.
|
||||
/// </summary>
|
||||
public sealed class SettlementQueue
|
||||
{
|
||||
public static readonly TimeSpan Timeout = TimeSpan.FromMinutes(30);
|
||||
|
||||
private readonly List<PendingSettlement> _items = [];
|
||||
|
||||
public IReadOnlyList<PendingSettlement> Items => _items;
|
||||
|
||||
public int Count => _items.Count;
|
||||
|
||||
/// <summary>The oldest close still waiting, or null.</summary>
|
||||
public DateTime? OldestClosedUtc => _items.Count == 0 ? null : _items.Min(static s => s.ClosedUtc);
|
||||
|
||||
public bool Contains(long positionId) => _items.Any(s => s.Ids.Contains(positionId));
|
||||
|
||||
/// <summary>Adds a close; a second one with the same key is ignored.</summary>
|
||||
public bool Add(PendingSettlement settlement)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(settlement);
|
||||
if (_items.Any(s => s.Key == settlement.Key))
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
_items.Add(settlement);
|
||||
return true;
|
||||
}
|
||||
|
||||
public void Clear() => _items.Clear();
|
||||
|
||||
/// <summary>Drops the items whose row is already written (a stop between the row and the state): returns how many.</summary>
|
||||
public int RemoveWritten(IReadOnlySet<string> writtenKeys)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(writtenKeys);
|
||||
return _items.RemoveAll(s => writtenKeys.Contains(s.Key));
|
||||
}
|
||||
|
||||
/// <summary>Settles what the history confirms, and — past the timeout — what it does not, with the estimate.</summary>
|
||||
public List<SettledOutcome> Resolve(IReadOnlyList<ClosedTrade> history, DateTime nowUtc)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
List<SettledOutcome> done = [];
|
||||
foreach (PendingSettlement s in _items.ToList())
|
||||
{
|
||||
Settlement r = RealizedSettlement.Of(s.Ids, history);
|
||||
if (s.Ids.Length > 0 && r.Complete)
|
||||
{
|
||||
done.Add(Settle(s, r.GrossUsd, r.NetUsd, SettlementSource.Venue));
|
||||
_items.Remove(s);
|
||||
}
|
||||
else if (nowUtc - s.ClosedUtc >= Timeout)
|
||||
{
|
||||
done.Add(Settle(s, s.Row.PnlGrossUsd, s.Estimate, SettlementSource.Estimate));
|
||||
_items.Remove(s);
|
||||
}
|
||||
}
|
||||
|
||||
return done;
|
||||
}
|
||||
|
||||
/// <summary>The row as written: the numbers, and in the motivation where they came from.</summary>
|
||||
public static SettledOutcome Settle(PendingSettlement s, double gross, double net, SettlementSource source)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(s);
|
||||
string note = source switch
|
||||
{
|
||||
SettlementSource.Venue => BasketCorrections.VenueMarker + " (netProfit − fees)",
|
||||
SettlementSource.Estimate => BasketCorrections.EstimateMarker + " dai prezzi di chiusura: lo storico eToro non mostrava le posizioni dopo 30 min",
|
||||
_ => "P&L: simulatore",
|
||||
};
|
||||
BasketOutcomeRow row = s.Row with { PnlGrossUsd = gross, PnlNetUsd = net, Motivazione = $"{s.Row.Motivazione} | {note}" };
|
||||
return new SettledOutcome(s, row, gross, net, source);
|
||||
}
|
||||
|
||||
/// <summary>When to read the history again: every 5 s in the first minute after a close, every 30 s while anything waits, every 5 min otherwise.</summary>
|
||||
public TimeSpan NextCheckIn(DateTime nowUtc) =>
|
||||
_items.Count == 0 ? TimeSpan.FromMinutes(5)
|
||||
: _items.Any(s => nowUtc - s.ClosedUtc < TimeSpan.FromMinutes(1)) ? TimeSpan.FromSeconds(5)
|
||||
: TimeSpan.FromSeconds(30);
|
||||
|
||||
public void Write(Utf8JsonWriter w, string propertyName)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
w.WriteStartArray(propertyName);
|
||||
foreach (PendingSettlement s in _items)
|
||||
{
|
||||
s.Write(w);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
}
|
||||
|
||||
/// <summary>Replaces the content with the items of a saved array; damaged items are skipped. Returns how many were read.</summary>
|
||||
public int Load(JsonElement array)
|
||||
{
|
||||
_items.Clear();
|
||||
if (array.ValueKind != JsonValueKind.Array)
|
||||
{
|
||||
return 0;
|
||||
}
|
||||
|
||||
foreach (JsonElement e in array.EnumerateArray())
|
||||
{
|
||||
if (PendingSettlement.Read(e) is { } s && s.Key.Length > 0)
|
||||
{
|
||||
Add(s);
|
||||
}
|
||||
}
|
||||
|
||||
return _items.Count;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,178 @@
|
||||
using System.Globalization;
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
|
||||
namespace Encelado.Core.Baskets.Learning;
|
||||
|
||||
/// <summary>What the training of a cycle produced: the logistic with its walk-forward, the challenger (when trained), the level-0 tables.</summary>
|
||||
public sealed record CycleTraining(LogisticWalkForward Logistic, ModelReport? MlpReport, SmallMlp? Mlp, bool ChallengerWins, IReadOnlyList<CalibrationTables.Row> Calibration);
|
||||
|
||||
/// <summary>
|
||||
/// The training of a learning cycle (§8.7), pure and cancellable: the logistic evaluated walk-
|
||||
/// forward and retrained on every row, the MLP challenger in purged folds only when the
|
||||
/// operator turned it on (<c>learning.enabled</c> and <c>learning.challenger</c>), the
|
||||
/// calibration tables. No file, no lock, no clock: the engine runs it on a background thread
|
||||
/// and applies the result on its decision thread.
|
||||
/// </summary>
|
||||
public static class CycleTrainer
|
||||
{
|
||||
/// <summary>The challenger "wins" when its walk-forward AUC beats the logistic's by this much (promotion still needs the forward test).</summary>
|
||||
public const double ChallengerMargin = 0.01;
|
||||
|
||||
public static CycleTraining Train(IReadOnlyList<LabelledBasket> rows, double pMin, bool trainChallenger, Action<string>? phase, CancellationToken ct)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
phase?.Invoke("logistica");
|
||||
LogisticWalkForward l1 = ModelEvaluator.EvaluateLogisticWalkForward(rows, pMin, ct);
|
||||
ModelReport? l2 = null;
|
||||
SmallMlp? mlp = null;
|
||||
if (trainChallenger)
|
||||
{
|
||||
phase?.Invoke("mlp");
|
||||
(l2, mlp) = ModelEvaluator.EvaluateMlp(rows, pMin, ct: ct);
|
||||
}
|
||||
|
||||
ct.ThrowIfCancellationRequested();
|
||||
bool wins = mlp is not null && l2 is not null && double.IsFinite(l2.Auc) && double.IsFinite(l1.Report.Auc) && l2.Auc >= l1.Report.Auc + ChallengerMargin;
|
||||
return new CycleTraining(l1, l2, mlp, wins, CalibrationTables.Build(rows));
|
||||
}
|
||||
|
||||
/// <summary>The fingerprint of a dataset: SHA-256 of <c>id:label;</c> over the rows in order, 16 hex characters.</summary>
|
||||
public static string DatasetHash(IReadOnlyList<LabelledBasket> rows)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
StringBuilder sb = new();
|
||||
foreach (LabelledBasket r in rows)
|
||||
{
|
||||
sb.Append(r.BasketId).Append(':').Append(r.Label).Append(';');
|
||||
}
|
||||
|
||||
return Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(sb.ToString())))[..16].ToLowerInvariant();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The knowledge files a cycle writes, as text. Pure.</summary>
|
||||
public static class LearningKnowledge
|
||||
{
|
||||
public const string RegistryHeader = "versione;data;tipo;n_train;auc_wf;brier;logloss;stato;motivazione";
|
||||
|
||||
public const string ProposalsHeader = "data;origine;parametro;valore_attuale;valore_proposto;evidenza;stato;motivazione";
|
||||
|
||||
/// <summary>
|
||||
/// The weekly insights file of <paramref name="nowUtc"/>: <c>insights_YYYYWW.md</c> with the
|
||||
/// ISO week and <b>its</b> year (5.1: the first days of January belong to the previous
|
||||
/// year's week 52 or 53, or December's last days to the next year's week 1).
|
||||
/// </summary>
|
||||
public static string InsightsFileName(DateTime nowUtc) =>
|
||||
string.Create(CultureInfo.InvariantCulture, $"insights_{ISOWeek.GetYear(nowUtc)}{ISOWeek.GetWeekOfYear(nowUtc):00}.md");
|
||||
|
||||
/// <summary>The level-0 table as <c>calibration.csv</c>.</summary>
|
||||
public static string CalibrationCsv(IReadOnlyList<CalibrationTables.Row> rows)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
StringBuilder sb = new();
|
||||
sb.AppendLine(CalibrationTables.Header);
|
||||
foreach (CalibrationTables.Row r in rows)
|
||||
{
|
||||
sb.AppendLine(r.ToCsv());
|
||||
}
|
||||
|
||||
return sb.ToString();
|
||||
}
|
||||
|
||||
/// <summary>The insights markdown: counts, level 0, the walk-forward of both models, the bandit's arms, the rule on proposals.</summary>
|
||||
public static string Insights(DateTime nowUtc, IReadOnlyList<LabelledBasket> rows, ModelReport l1, ModelReport? l2, IReadOnlyList<CalibrationTables.Row> calibration, IReadOnlyList<string> banditLines)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
ArgumentNullException.ThrowIfNull(l1);
|
||||
ArgumentNullException.ThrowIfNull(calibration);
|
||||
ArgumentNullException.ThrowIfNull(banditLines);
|
||||
int week = ISOWeek.GetWeekOfYear(nowUtc);
|
||||
StringBuilder sb = new();
|
||||
sb.AppendLine(CultureInfo.InvariantCulture, $"# Insight settimanali — {nowUtc:yyyy-MM-dd} (settimana {week} del {ISOWeek.GetYear(nowUtc)})");
|
||||
sb.AppendLine();
|
||||
if (rows.Count > 0)
|
||||
{
|
||||
sb.AppendLine(CultureInfo.InvariantCulture, $"Basket chiusi nel ledger: **{rows.Count}**, win rate {rows.Average(static r => r.Label):P0}, P&L netto {rows.Sum(static r => r.PnlNetUsd):F2} USD.");
|
||||
}
|
||||
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("## Cosa ha funzionato e cosa no (calibrazione, livello 0)");
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("| dimensione | bucket | n | win rate | P&L medio |");
|
||||
sb.AppendLine("|---|---|---|---|---|");
|
||||
foreach (CalibrationTables.Row r in calibration.Where(static r => r.Count >= 5))
|
||||
{
|
||||
sb.AppendLine(CultureInfo.InvariantCulture, $"| {r.Dimension} | {r.Bucket} | {r.Count} | {r.WinRate:P0} | {r.MeanPnl:F2} |");
|
||||
}
|
||||
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("## Meta-modello (livelli 1 e 2, walk-forward)");
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("- " + l1.Summary);
|
||||
sb.AppendLine("- " + (l2?.Summary ?? "challenger MLP non addestrato (learning.challenger spento)"));
|
||||
if (l1.Calibration.Count > 0)
|
||||
{
|
||||
sb.AppendLine("- calibrazione logistica: " + ModelEvaluator.DescribeCalibration(l1.Calibration));
|
||||
}
|
||||
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("## Bandit (livello 3)");
|
||||
sb.AppendLine();
|
||||
foreach (string line in banditLines)
|
||||
{
|
||||
sb.AppendLine("- " + line);
|
||||
}
|
||||
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("## Parametri suggeriti");
|
||||
sb.AppendLine();
|
||||
sb.AppendLine("Nessun parametro live viene cambiato da questo file: le proposte sono in `proposals.csv` e passano dal forward test pre-registrato.");
|
||||
return sb.ToString();
|
||||
}
|
||||
|
||||
/// <summary>The lines a cycle appends to <c>proposals.csv</c>: the gate (one per cycle) and the baskets that lose over 30 closes or more.</summary>
|
||||
public static IReadOnlyList<string> Proposals(DateTime nowUtc, IReadOnlyList<LabelledBasket> rows, ModelReport l1, bool wasActive)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
ArgumentNullException.ThrowIfNull(l1);
|
||||
List<string> lines =
|
||||
[
|
||||
string.Create(CultureInfo.InvariantCulture,
|
||||
$"{nowUtc:O};ciclo settimanale;mlMinProbability gate;{(wasActive ? "attivo" : "ombra")};{(l1.PassesActivation ? "attivo" : "ombra")};AUC {l1.Auc:F3} su {rows.Count} basket, P&L filtrato {l1.PnlFiltered:F0} contro {l1.PnlAll:F0};proposta;{Clean(l1.Motivazione)}"),
|
||||
];
|
||||
|
||||
foreach (IGrouping<string, LabelledBasket> g in rows.GroupBy(static r => r.Basket).OrderBy(static g => g.Key, StringComparer.Ordinal))
|
||||
{
|
||||
int n = g.Count();
|
||||
double pnl = g.Sum(static r => r.PnlNetUsd);
|
||||
if (n >= 30 && pnl < 0)
|
||||
{
|
||||
lines.Add(string.Create(CultureInfo.InvariantCulture,
|
||||
$"{nowUtc:O};ciclo settimanale;baskets[{g.Key}].enabled;true;false;{n} basket, P&L netto {pnl:F0} USD, win rate {g.Average(static r => r.Label):P0};proposta;il basket perde in modo persistente: da valutare nel forward test prima di disattivarlo"));
|
||||
}
|
||||
}
|
||||
|
||||
return lines;
|
||||
}
|
||||
|
||||
/// <summary>The lines a cycle appends to <c>models_registry.csv</c>: the logistic and, when trained, the challenger.</summary>
|
||||
public static IReadOnlyList<string> Registry(int version, DateTime nowUtc, int rows, ModelReport l1, bool active, ModelReport? l2, bool challengerWins)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(l1);
|
||||
List<string> lines =
|
||||
[
|
||||
string.Create(CultureInfo.InvariantCulture, $"v{version};{nowUtc:O};logistica;{rows};{l1.Auc:F3};{l1.Brier:F3};{l1.LogLoss:F3};{(active ? "champion attivo" : "champion in ombra")};{Clean(l1.Motivazione)}"),
|
||||
];
|
||||
if (l2 is not null)
|
||||
{
|
||||
lines.Add(string.Create(CultureInfo.InvariantCulture,
|
||||
$"v{version};{nowUtc:O};mlp16;{rows};{l2.Auc:F3};{l2.Brier:F3};{l2.LogLoss:F3};challenger;{(challengerWins ? "batte la logistica per AUC di almeno 0,01: promozione solo con il P&L del forward test" : Clean(l2.Motivazione))}"));
|
||||
}
|
||||
|
||||
return lines;
|
||||
}
|
||||
|
||||
/// <summary>A text for a <c>;</c>-separated column: no separators, no line breaks.</summary>
|
||||
public static string Clean(string text) => (text ?? string.Empty).Replace(';', ',').Replace('\n', ' ').Replace('\r', ' ');
|
||||
}
|
||||
@@ -0,0 +1,348 @@
|
||||
using System.Globalization;
|
||||
using Encelado.Core.Baskets.History;
|
||||
using Encelado.Core.Ml;
|
||||
|
||||
namespace Encelado.Core.Baskets.Learning;
|
||||
|
||||
/// <summary>The gate of ADR-0006 in one place: the meta-model filters an entry only when the operator turned learning on, the activation passed and a probability exists.</summary>
|
||||
public static class MlGate
|
||||
{
|
||||
public static bool IsActive(bool learningEnabled, bool activationPassed, double pMl) => learningEnabled && activationPassed && double.IsFinite(pMl);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// How the probabilities given at entry fared once the baskets closed (5.1): the rolling AUC
|
||||
/// the deactivation watches, with its bootstrap interval, the Brier score, the log-loss, the
|
||||
/// hit rate, the calibration. Pure.
|
||||
/// </summary>
|
||||
public static class RollingMetrics
|
||||
{
|
||||
public const int Window = 100;
|
||||
public const int LongWindow = 200;
|
||||
|
||||
/// <summary>Below this many pairs the AUC says nothing (the rule of <see cref="ModelEvaluator.RollingAuc"/>).</summary>
|
||||
public const int MinCount = 20;
|
||||
|
||||
public static RollingPerformance Compute(IReadOnlyList<(double P, int Label)> recent, IReadOnlyList<AucPoint> history, double lastOutcomes10, int seed = 42)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(recent);
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
int n = recent.Count;
|
||||
(double[] p100, int[] y100) = Tail(recent, Window);
|
||||
(double[] p200, int[] y200) = Tail(recent, LongWindow);
|
||||
double auc100 = n >= MinCount ? Classification.Auc(p100, y100) : double.NaN;
|
||||
double auc200 = n >= MinCount ? Classification.Auc(p200, y200) : double.NaN;
|
||||
(double lo, double hi) = n >= MinCount ? ModelEvaluator.BootstrapAuc(p100, y100, 200, seed) : (double.NaN, double.NaN);
|
||||
bool any = p100.Length > 0;
|
||||
(double[] allP, int[] allY) = Tail(recent, n);
|
||||
return new RollingPerformance(
|
||||
n,
|
||||
RollingPerformance.AtEntry,
|
||||
auc100,
|
||||
auc200,
|
||||
lo,
|
||||
hi,
|
||||
any ? Classification.Brier(p100, y100) : double.NaN,
|
||||
any ? Classification.LogLoss(p100, y100) : double.NaN,
|
||||
any ? y100.Average() : double.NaN,
|
||||
any ? p100.Average() : double.NaN,
|
||||
lastOutcomes10,
|
||||
allP,
|
||||
allY,
|
||||
[.. history],
|
||||
n > 0 ? Classification.Calibration(allP, allY, 10) : []);
|
||||
}
|
||||
|
||||
private static (double[] P, int[] Y) Tail(IReadOnlyList<(double P, int Label)> recent, int count)
|
||||
{
|
||||
int start = Math.Max(0, recent.Count - count);
|
||||
double[] p = new double[recent.Count - start];
|
||||
int[] y = new int[recent.Count - start];
|
||||
for (int i = start; i < recent.Count; i++)
|
||||
{
|
||||
p[i - start] = recent[i].P;
|
||||
y[i - start] = recent[i].Label;
|
||||
}
|
||||
|
||||
return (p, y);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The training set in numbers (the Apprendimento page's dataset panel). Pure.</summary>
|
||||
public static class DatasetStats
|
||||
{
|
||||
/// <summary>The modes whose closes count toward the 300 of ADR-0006 (<c>LEDGER_SCHEMA.md</c>: Demo, and the 4.0 names).</summary>
|
||||
public static bool IsDemo(string mode) => mode is "Demo" or "DemoApprove" or "DemoAuto";
|
||||
|
||||
/// <param name="all">Every row of <c>baskets.csv</c>, corrected.</param>
|
||||
/// <param name="training">The outcome rows of the baskets that make the training set (label and entry features).</param>
|
||||
/// <param name="withoutEntryRow">Labelled baskets with no <c>ingresso</c> line.</param>
|
||||
/// <param name="entryRowsWithoutFeatures">Labelled baskets whose <c>ingresso</c> line carries no features.</param>
|
||||
public static DatasetSummary Build(IReadOnlyList<BasketOutcomeRow> all, IReadOnlyList<BasketOutcomeRow> training, int withoutEntryRow, int entryRowsWithoutFeatures, string datasetHash, DateTime computedUtc)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(all);
|
||||
ArgumentNullException.ThrowIfNull(training);
|
||||
int labelled = training.Count;
|
||||
int wins = training.Count(static r => r.Label == 1);
|
||||
double[] pnl = [.. training.Select(static r => r.PnlNetUsd).Where(double.IsFinite).Order()];
|
||||
(bool suspect, string reason) = LabelsSuspect(training);
|
||||
int target = ModelEvaluator.MinRowsForActivation;
|
||||
return new DatasetSummary(
|
||||
computedUtc,
|
||||
datasetHash,
|
||||
all.Count,
|
||||
labelled,
|
||||
withoutEntryRow,
|
||||
entryRowsWithoutFeatures,
|
||||
all.Count(static r => r.IsLoneLeg),
|
||||
all.Count(static r => r.Corrected),
|
||||
all.Count(static r => r.Unverified),
|
||||
wins,
|
||||
labelled - wins,
|
||||
labelled > 0 ? (double)wins / labelled : double.NaN,
|
||||
pnl.Sum(),
|
||||
pnl.Length > 0 ? pnl.Average() : double.NaN,
|
||||
Quantile(pnl, 0.5),
|
||||
Quantile(pnl, 0.05),
|
||||
training.Count > 0 ? training.Min(static r => r.OpenedUtc) : null,
|
||||
training.Count > 0 ? training.Max(static r => r.ClosedUtc) : null,
|
||||
all.Count(static r => r.HasLabel && !r.IsLoneLeg && IsDemo(r.Mode)),
|
||||
target,
|
||||
Math.Min(1, (double)labelled / target),
|
||||
[.. training.GroupBy(static r => r.Mode.Length > 0 ? r.Mode : "—").Select(static g => new KeyCount(g.Key, g.Count())).OrderByDescending(static k => k.Count).ThenBy(static k => k.Key, StringComparer.Ordinal)],
|
||||
Group(training, static r => r.Basket),
|
||||
Group(training, static r => r.Preset),
|
||||
Group(training, static r => r.ExitReason),
|
||||
suspect,
|
||||
reason);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Labels that look like the proceeds of 4.0.0–5.0.0 rather than profits: a win rate of 90 %
|
||||
/// or more on 20 baskets or more, a single basket whose P&L exceeds 5 % of the equity at
|
||||
/// its entry, or a P&L whose sign contradicts the net pips (gross pips − cost) in more
|
||||
/// than a fifth of the baskets where the pips say something clear (1 pip or more).
|
||||
/// </summary>
|
||||
public static (bool Suspect, string Reason) LabelsSuspect(IReadOnlyList<BasketOutcomeRow> rows)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
List<string> reasons = [];
|
||||
int n = rows.Count;
|
||||
if (n >= 20)
|
||||
{
|
||||
double winRate = rows.Average(static r => r.Label);
|
||||
if (winRate >= 0.9)
|
||||
{
|
||||
reasons.Add(It($"win rate {winRate * 100:0} % su {n} basket, troppo alto per questa strategia"));
|
||||
}
|
||||
}
|
||||
|
||||
int big = rows.Count(static r => double.IsFinite(r.EquityAtEntry) && r.EquityAtEntry > 0 && double.IsFinite(r.PnlNetUsd) && Math.Abs(r.PnlNetUsd) > 0.05 * r.EquityAtEntry);
|
||||
if (big > 0)
|
||||
{
|
||||
reasons.Add(It($"{big} basket con un P&L oltre il 5 % dell'equity all'ingresso"));
|
||||
}
|
||||
|
||||
int clear = 0, disagree = 0;
|
||||
foreach (BasketOutcomeRow r in rows)
|
||||
{
|
||||
double net = r.PipsGross - r.CostPips;
|
||||
if (!double.IsFinite(net) || Math.Abs(net) < 1 || !double.IsFinite(r.PnlNetUsd) || r.PnlNetUsd == 0)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
clear++;
|
||||
if (Math.Sign(net) != Math.Sign(r.PnlNetUsd))
|
||||
{
|
||||
disagree++;
|
||||
}
|
||||
}
|
||||
|
||||
if (clear >= 10 && disagree > 0.2 * clear)
|
||||
{
|
||||
reasons.Add(It($"il segno del P&L contraddice i pip netti in {disagree} basket su {clear}"));
|
||||
}
|
||||
|
||||
return (reasons.Count > 0, string.Join("; ", reasons));
|
||||
}
|
||||
|
||||
private static List<GroupStats> Group(IReadOnlyList<BasketOutcomeRow> rows, Func<BasketOutcomeRow, string> key) =>
|
||||
[
|
||||
.. rows.GroupBy(r => key(r) is { Length: > 0 } k ? k : "—", StringComparer.Ordinal)
|
||||
.Select(static g =>
|
||||
{
|
||||
double[] pnl = [.. g.Select(static r => r.PnlNetUsd).Where(double.IsFinite)];
|
||||
return new GroupStats(g.Key, g.Count(), g.Average(static r => r.Label), pnl.Sum(), pnl.Length > 0 ? pnl.Average() : double.NaN);
|
||||
})
|
||||
.OrderByDescending(static s => s.Count)
|
||||
.ThenBy(static s => s.Key, StringComparer.Ordinal),
|
||||
];
|
||||
|
||||
/// <summary>The nearest-rank quantile of sorted values; NaN when empty.</summary>
|
||||
public static double Quantile(IReadOnlyList<double> sorted, double q)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(sorted);
|
||||
if (sorted.Count == 0)
|
||||
{
|
||||
return double.NaN;
|
||||
}
|
||||
|
||||
if (q == 0.5)
|
||||
{
|
||||
int mid = sorted.Count / 2;
|
||||
return sorted.Count % 2 == 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
|
||||
}
|
||||
|
||||
return sorted[Math.Clamp((int)Math.Floor(q * (sorted.Count - 1)), 0, sorted.Count - 1)];
|
||||
}
|
||||
|
||||
private static string It(FormattableString s) => s.ToString(CultureInfo.InvariantCulture);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The activation of the gate, condition by condition (§8.3 and ADR-0006): the walk-forward of
|
||||
/// the last cycle, the Demo closes, the forward test, the operator's switch and — while active
|
||||
/// — the rolling AUC. Pure.
|
||||
/// </summary>
|
||||
public static class ActivationRules
|
||||
{
|
||||
public static ActivationChecklist Build(CycleSummary? lastCycle, DatasetSummary? dataset, bool operatorEnabled, bool activeFlag, RollingPerformance rolling, ForwardSummary? forward)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rolling);
|
||||
ModelEvaluation? l = lastCycle?.Logistic;
|
||||
int target = ModelEvaluator.MinRowsForActivation;
|
||||
int rows = l?.Rows ?? dataset?.LabelledRows ?? 0;
|
||||
List<ActivationItem> items =
|
||||
[
|
||||
new("rows", "Basket etichettati", Int(rows), It($"≥ {target}"), rows >= target, l is null ? "dataset" : "ultimo ciclo"),
|
||||
new("auc", "AUC walk-forward", Num(l?.Auc, "0.000"), "≥ " + Dec(ModelEvaluator.MinAuc, "0.00"), l is null || !double.IsFinite(l.Auc) ? null : l.Auc >= ModelEvaluator.MinAuc, "ultimo ciclo"),
|
||||
new("aucLow", "Estremo inferiore IC 95 %", Num(l?.AucLow, "0.000"), "> 0,50", l is null || !double.IsFinite(l.AucLow) ? null : l.AucLow > 0.5, "ultimo ciclo (bootstrap)"),
|
||||
new("pnlFilter", "P&L filtrato > P&L totale", l is null ? "—" : $"{Dec(l.PnlFilteredUsd, "0")} contro {Dec(l.PnlAllUsd, "0")} USD", "filtrato > totale",
|
||||
l is null || !double.IsFinite(l.Auc) ? null : l.PnlFilteredUsd > l.PnlAllUsd, "ultimo ciclo"),
|
||||
new("dsr", "DSR del filtrato", Num(l?.DsrFiltered, "0.00"), "≥ " + Dec(ModelEvaluator.MinDsr, "0.00"), l is null || !double.IsFinite(l.DsrFiltered) ? null : l.DsrFiltered >= ModelEvaluator.MinDsr, "ultimo ciclo"),
|
||||
new("demo300", "Chiusi in Demo", dataset is null ? "—" : Int(dataset.DemoClosed), It($"≥ {target}"), dataset is null ? null : dataset.DemoClosed >= target, "baskets.csv (ADR-0006)"),
|
||||
new("forwardPnl", "P&L netto forward pre-registrato", forward is null ? "—" : $"{Dec(forward.PnlNetUsd, "0.00")} USD su {Int(forward.Rows)} righe", "≥ 0",
|
||||
forward is null ? null : forward.PnlNetUsd >= 0, forward is null ? "knowledge/forward_registry.csv assente" : "knowledge/forward_registry.csv"),
|
||||
new("operator", "learning.enabled", operatorEnabled ? "sì" : "no", "sì", operatorEnabled, "Impostazioni ▸ Strategia (decide l'operatore)"),
|
||||
new("rollingAuc", "AUC mobile 100 (guardia)", Num(rolling.Auc100, "0.000"), "≥ " + Dec(ModelEvaluator.DeactivationAuc, "0.00") + " mentre è attivo",
|
||||
!activeFlag || !double.IsFinite(rolling.Auc100) ? null : rolling.Auc100 >= ModelEvaluator.DeactivationAuc, "probabilità all'ingresso dei basket chiusi"),
|
||||
];
|
||||
|
||||
bool walkForward = l?.PassesActivation == true;
|
||||
bool adr = dataset is not null && dataset.DemoClosed >= target && forward is not null && forward.PnlNetUsd >= 0;
|
||||
string why = walkForward && adr && operatorEnabled
|
||||
? "tutte le condizioni sono soddisfatte: il cancello filtra gli ingressi"
|
||||
: string.Join("; ", new[]
|
||||
{
|
||||
l is null ? "nessun ciclo eseguito: la valutazione walk-forward manca" : !walkForward ? "walk-forward: " + l.Motivazione : null,
|
||||
!adr ? It($"ADR-0006: servono {target} basket chiusi in Demo (ora {dataset?.DemoClosed ?? 0}) e un P&L forward ≥ 0 sulla pre-registrazione") : null,
|
||||
!operatorEnabled ? "l'operatore non ha acceso l'apprendimento (learning.enabled)" : null,
|
||||
}.Where(static s => s is not null));
|
||||
return new ActivationChecklist(walkForward, adr, operatorEnabled, why, items);
|
||||
}
|
||||
|
||||
private static string Int(int v) => v.ToString(CultureInfo.InvariantCulture);
|
||||
|
||||
private static string Num(double? v, string format) => v is { } x && double.IsFinite(x) ? Dec(x, format) : "—";
|
||||
|
||||
/// <summary>A number in the Italian way for a text (decimal comma).</summary>
|
||||
public static string Dec(double v, string format) => double.IsFinite(v) ? v.ToString(format, CultureInfo.InvariantCulture).Replace('.', ',') : "—";
|
||||
|
||||
private static string It(FormattableString s) => s.ToString(CultureInfo.InvariantCulture);
|
||||
}
|
||||
|
||||
/// <summary>Rows of the page built from the pure pictures of the models. Pure.</summary>
|
||||
public static class LearningRows
|
||||
{
|
||||
/// <summary>The volatility forecaster of a basket; null before its first bar.</summary>
|
||||
public static BasketVolRow? Vol(VolStats s, int context, double volScaleMin, double volScaleMax)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(s);
|
||||
if (s.Bars == 0)
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
double ratio = s.Ratio;
|
||||
return new BasketVolRow(s.Bars, s.ActiveModel, s.EwmaSigma, s.HarSigma, s.ForecastSigma, s.Average30dSigma, ratio,
|
||||
double.IsFinite(ratio) ? Math.Clamp(ratio, volScaleMin, volScaleMax) : double.NaN, s.RmseEwma, s.RmseHar, s.Scored, s.Pending, s.LastHarFitUtc,
|
||||
context, ThompsonBandit.ContextLabel(context));
|
||||
}
|
||||
|
||||
/// <summary>The terciles of the σ forecasts at the closes (the bandit's context); NaN below nine values, as the bandit rule.</summary>
|
||||
public static VolatilityContextSummary VolContext(IReadOnlyList<double> history)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
double[] sorted = [.. history.Where(double.IsFinite).Order()];
|
||||
return sorted.Length < 9
|
||||
? new VolatilityContextSummary(history.Count, double.NaN, double.NaN)
|
||||
: new VolatilityContextSummary(history.Count, sorted[sorted.Length / 3], sorted[2 * sorted.Length / 3]);
|
||||
}
|
||||
|
||||
/// <summary>The kind of an engine's probability: the entry's while the basket holds (or waits for) a position, the last bar close's otherwise.</summary>
|
||||
public static string KindOf(bool atEntry) => atEntry ? BasketLearningRow.KindAtEntry : BasketLearningRow.KindLastBar;
|
||||
|
||||
/// <summary>
|
||||
/// One basket as the meta-model sees it: p and the kind of reading it is, what pushes it (the
|
||||
/// five largest |w·z|), the full vector, the volatility. The contributions are shown only when
|
||||
/// they give back the p shown (5.1 review): an explanation of another model, or of another
|
||||
/// moment, is left out rather than put next to a probability it did not produce.
|
||||
/// </summary>
|
||||
public static BasketLearningRow Basket(string name, string cross, bool enabled, string state, double pMl, DateTime? pMlUtc, string kind, double pMin,
|
||||
ScoreExplanation explained, BasketVolRow? vol)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(explained);
|
||||
bool known = double.IsFinite(pMl);
|
||||
bool explains = explained.Explains(pMl);
|
||||
IReadOnlyList<FeatureValue> features = explains ? explained.Features : [];
|
||||
return new BasketLearningRow(name, cross, enabled, state, pMl, known ? pMlUtc : null, known ? kind : string.Empty, known && pMl < pMin,
|
||||
OnlineLogistic.Top(features, 5), features, vol)
|
||||
{
|
||||
Intercept = explains ? explained.Intercept : double.NaN,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>When the weekly cycle runs (§8.7): Sunday from 10:00 UTC, once seven days have passed since the last one. Pure.</summary>
|
||||
public static class LearningSchedule
|
||||
{
|
||||
/// <summary>The first instant at or after <paramref name="nowUtc"/> (and at least seven days after the last cycle) that falls on a Sunday from 10:00 UTC.</summary>
|
||||
public static DateTime NextDue(DateTime? lastCycleUtc, DateTime nowUtc)
|
||||
{
|
||||
DateTime basis = lastCycleUtc is { } last && last > DateTime.MinValue.AddDays(7) ? last.AddDays(7) : nowUtc;
|
||||
if (basis < nowUtc)
|
||||
{
|
||||
basis = nowUtc;
|
||||
}
|
||||
|
||||
for (int i = 0; i < 8; i++)
|
||||
{
|
||||
DateTime day = basis.Date.AddDays(i);
|
||||
if (day.DayOfWeek != DayOfWeek.Sunday)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
DateTime ten = day.AddHours(10);
|
||||
DateTime candidate = basis > ten ? basis : ten;
|
||||
if (candidate.Date == day)
|
||||
{
|
||||
return DateTime.SpecifyKind(candidate, DateTimeKind.Utc);
|
||||
}
|
||||
}
|
||||
|
||||
return DateTime.SpecifyKind(basis.Date.AddDays(7).AddHours(10), DateTimeKind.Utc);
|
||||
}
|
||||
|
||||
/// <summary>Whether the weekly cycle would start now (the engine's own rule).</summary>
|
||||
public static bool IsDue(DateTime? lastCycleUtc, DateTime nowUtc) => nowUtc >= NextDue(lastCycleUtc, nowUtc);
|
||||
|
||||
public static CycleSchedule Build(DateTime? lastCycleUtc, bool runsInBot, CycleRunStatus run, CycleSummary? lastCycle, DateTime nowUtc)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(run);
|
||||
DateTime? next = runsInBot ? NextDue(lastCycleUtc, nowUtc) : null;
|
||||
return new CycleSchedule(lastCycleUtc, next, runsInBot, runsInBot && next is { } n && nowUtc >= n, run.Running, run.RunningSinceUtc, run.Phase,
|
||||
run.LastDurationMs ?? lastCycle?.DurationMs, run.LastError, run.LastTrigger.Length > 0 ? run.LastTrigger : lastCycle?.Trigger ?? string.Empty);
|
||||
}
|
||||
}
|
||||
@@ -20,8 +20,32 @@ public static class LearningFeatures
|
||||
"volRatio", "lastNOutcomes", "buy_cross",
|
||||
];
|
||||
|
||||
/// <summary>What each feature is, in Italian for the interface, in the order of <see cref="Names"/>.</summary>
|
||||
public static readonly string[] Labels =
|
||||
[
|
||||
"z-score del cross", "|z|", "correlazione ρ sulla finestra", "correlazione ρ su 20 barre", "emivita (barre)", "ATR gamba A (pip)", "ATR gamba B (pip)",
|
||||
"deviazione standard del cross", "volatilità EWMA del cross", "forza del trend (tipo ADX)",
|
||||
"costo stimato (pip)", "spread gamba A (pip)", "spread gamba B (pip)", "ora del giorno (seno)", "ora del giorno (coseno)", "giorno della settimana",
|
||||
"minuti al prossimo evento ad alto impatto", "minuti dall'ultimo evento ad alto impatto", "sorpresa dell'ultimo dato",
|
||||
"differenza di sentiment 1 h", "differenza di sentiment 4 h", "differenza di sentiment 24 h", "differenza hawkish", "risk-off", "notizie nelle ultime 24 h",
|
||||
"volatilità prevista / media 30 g", "esito medio degli ultimi 10 basket", "acquisto del cross",
|
||||
];
|
||||
|
||||
public static int Count => Names.Length;
|
||||
|
||||
/// <summary>The Italian label of a feature name, or the name itself when unknown.</summary>
|
||||
public static string LabelOf(string name)
|
||||
{
|
||||
int i = Array.IndexOf(Names, name);
|
||||
return i >= 0 && i < Labels.Length ? Labels[i] : name;
|
||||
}
|
||||
|
||||
/// <summary>Position of <c>volRatio</c> in the vector.</summary>
|
||||
public static readonly int VolRatioIndex = Array.IndexOf(Names, "volRatio");
|
||||
|
||||
/// <summary>Position of <c>lastNOutcomes</c> in the vector (26): the mean of the last ten labels, masked to 0.5 where the labels were proceeds-based.</summary>
|
||||
public static readonly int LastOutcomesIndex = Array.IndexOf(Names, "lastNOutcomes");
|
||||
|
||||
public static double[] From(BasketContext ctx, BasketEvaluation e, bool buyCross)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(ctx);
|
||||
@@ -37,24 +61,108 @@ public static class LearningFeatures
|
||||
];
|
||||
}
|
||||
|
||||
/// <summary>Rebuilds the vector from a ledger line (an <c>ingresso</c> row of decisions.jsonl).</summary>
|
||||
/// <summary>The name of the array a ledger note carries the vector in (the <c>ingresso</c> of an entry completed after a pending leg).</summary>
|
||||
public const string VectorField = "features";
|
||||
|
||||
/// <summary>
|
||||
/// Rebuilds the vector from a ledger line (an <c>ingresso</c> row of decisions.jsonl); null
|
||||
/// when the line is not an entry or carries no features (5.1: an entry note without them
|
||||
/// is not a training row — an all-defaults vector would be a made-up one).
|
||||
/// </summary>
|
||||
public static double[]? FromLedgerLine(string jsonLine, out string basketId, out DateTime ts)
|
||||
{
|
||||
basketId = string.Empty;
|
||||
ts = default;
|
||||
EntryLine? entry = ReadEntryLine(jsonLine);
|
||||
basketId = entry?.BasketId ?? string.Empty;
|
||||
ts = entry?.Ts ?? default;
|
||||
return entry?.Features;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// An <c>ingresso</c> line of the decisions ledger: the basket, the time, the probability
|
||||
/// the meta-model gave at the decision (<c>p_ML</c>, NaN when absent) and the features —
|
||||
/// from the evaluation's named fields (a decision line: it has <c>config_hash</c>), or from
|
||||
/// the <see cref="VectorField"/> array (a note written when an entry completed after a
|
||||
/// pending leg), or null (a note without them). Null when the line is not an entry.
|
||||
/// Throws <see cref="JsonException"/> on a damaged line.
|
||||
/// </summary>
|
||||
public static EntryLine? ReadEntryLine(string jsonLine)
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(jsonLine);
|
||||
JsonElement r = doc.RootElement;
|
||||
if (!r.TryGetProperty("evento", out JsonElement ev) || ev.GetString() != "ingresso")
|
||||
if (r.ValueKind != JsonValueKind.Object || !r.TryGetProperty("evento", out JsonElement ev) || ev.ValueKind != JsonValueKind.String || ev.GetString() != "ingresso")
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
basketId = r.TryGetProperty("basket_id", out JsonElement b) ? b.GetString() ?? string.Empty : string.Empty;
|
||||
if (r.TryGetProperty("ts", out JsonElement t) && DateTime.TryParse(t.GetString(), CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out DateTime parsed))
|
||||
string basketId = r.TryGetProperty("basket_id", out JsonElement b) && b.ValueKind == JsonValueKind.String ? b.GetString() ?? string.Empty : string.Empty;
|
||||
DateTime ts = r.TryGetProperty("ts", out JsonElement t) && t.ValueKind == JsonValueKind.String &&
|
||||
DateTime.TryParse(t.GetString(), CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out DateTime parsed) ? parsed : default;
|
||||
double p = Num(r, "p_ML", double.NaN);
|
||||
|
||||
if (r.TryGetProperty(VectorField, out JsonElement vector) && vector.ValueKind == JsonValueKind.Array && vector.GetArrayLength() == Names.Length)
|
||||
{
|
||||
ts = parsed;
|
||||
double[] f = new double[Names.Length];
|
||||
int i = 0;
|
||||
foreach (JsonElement x in vector.EnumerateArray())
|
||||
{
|
||||
f[i] = x.ValueKind == JsonValueKind.Number && double.IsFinite(x.GetDouble()) ? x.GetDouble() : Neutral(i);
|
||||
i++;
|
||||
}
|
||||
|
||||
return new EntryLine(basketId, ts, f, p);
|
||||
}
|
||||
|
||||
return new EntryLine(basketId, ts, r.TryGetProperty("config_hash", out _) ? FromEvaluationFields(r) : null, p);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Any evaluation row of the decisions ledger (it has <c>config_hash</c>): the basket, the
|
||||
/// time, the event, the probability and the gate of that moment, the features and the
|
||||
/// volatility forecast. Null for a note (no evaluation). Throws <see cref="JsonException"/>
|
||||
/// on a damaged line. The page of a stopped bot shows each basket's last one.
|
||||
/// </summary>
|
||||
public static DecisionLine? ReadDecisionLine(string jsonLine)
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(jsonLine);
|
||||
JsonElement r = doc.RootElement;
|
||||
if (r.ValueKind != JsonValueKind.Object || !r.TryGetProperty("config_hash", out _))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
string Str(string name) => r.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.String ? v.GetString() ?? string.Empty : string.Empty;
|
||||
DateTime ts = DateTime.TryParse(Str("ts"), CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out DateTime t) ? t : default;
|
||||
return new DecisionLine(Str("basket"), Str("basket_id"), ts, Str("evento"), Num(r, "p_ML", double.NaN),
|
||||
r.TryGetProperty("mlActive", out JsonElement a) && a.ValueKind == JsonValueKind.True, FromEvaluationFields(r), Num(r, "sigmaForecast", double.NaN), Num(r, "sigmaAverage30d", double.NaN));
|
||||
}
|
||||
|
||||
/// <summary>Writes the vector as the <see cref="VectorField"/> array of a ledger note (NaN as the feature's neutral value).</summary>
|
||||
public static void WriteVector(Utf8JsonWriter w, IReadOnlyList<double> features)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
ArgumentNullException.ThrowIfNull(features);
|
||||
w.WriteStartArray(VectorField);
|
||||
for (int i = 0; i < features.Count; i++)
|
||||
{
|
||||
w.WriteNumberValue(double.IsFinite(features[i]) ? Math.Round(features[i], 8) : Neutral(i));
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
}
|
||||
|
||||
/// <summary>The value a missing feature takes (the same as the builders use).</summary>
|
||||
private static double Neutral(int index) => index >= 0 && index < Names.Length ? Names[index] switch
|
||||
{
|
||||
"halfLife" => 96,
|
||||
"regimeTrend" => 20,
|
||||
"minutesToNextHigh" or "minutesSinceLastHigh" => 1440,
|
||||
"volRatio" => 1,
|
||||
"lastNOutcomes" => 0.5,
|
||||
_ => 0,
|
||||
} : 0;
|
||||
|
||||
private static double[] FromEvaluationFields(JsonElement r)
|
||||
{
|
||||
double z = Num(r, "z", 0);
|
||||
double sf = Num(r, "sigmaForecast", double.NaN);
|
||||
double sa = Num(r, "sigmaAverage30d", double.NaN);
|
||||
@@ -81,5 +189,11 @@ public static class LearningFeatures
|
||||
r.TryGetProperty(name, out JsonElement p) && p.ValueKind == JsonValueKind.Number ? p.GetInt32() : int.MaxValue;
|
||||
}
|
||||
|
||||
/// <summary>An <c>ingresso</c> line: the basket, when, the probability at the decision (NaN when absent) and the features (null when the line carries none).</summary>
|
||||
public sealed record EntryLine(string BasketId, DateTime Ts, double[]? Features, double PAtEntry);
|
||||
|
||||
/// <summary>An evaluation row of the decisions ledger, as the learning page reads it.</summary>
|
||||
public sealed record DecisionLine(string Basket, string BasketId, DateTime Ts, string Evento, double PMl, bool MlActive, double[] Features, double SigmaForecast, double SigmaAverage30d);
|
||||
|
||||
/// <summary>One labelled basket for the learning stack.</summary>
|
||||
public sealed record LabelledBasket(string BasketId, DateTime OpenedUtc, DateTime ClosedUtc, double[] Features, int Label, double PnlNetUsd, string Basket, string Preset, double VolRatio);
|
||||
@@ -0,0 +1,771 @@
|
||||
using System.Globalization;
|
||||
using System.Text.Json;
|
||||
using Encelado.Core.Ml;
|
||||
|
||||
namespace Encelado.Core.Baskets.Learning;
|
||||
|
||||
/// <summary>
|
||||
/// The learning report as JSON, written by hand (no reflection, AOT-safe): the shape of
|
||||
/// <c>GET /api/learning</c> in docs/API.md — camelCase names, ISO-8601 UTC times, NaN and ∞
|
||||
/// as <c>null</c>. The same writers and readers keep the last cycle in
|
||||
/// <c>data/models/last_cycle.json</c>, so the page shows the same numbers whether the engine
|
||||
/// runs or not.
|
||||
/// </summary>
|
||||
public static class LearningJson
|
||||
{
|
||||
public const int CycleFileSchema = 1;
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// The report (docs/API.md, GET /api/learning)
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
/// <summary>The members of the report, inside an object the caller opened. <paramref name="allFeatures"/> adds every basket's full vector.</summary>
|
||||
public static void WriteMembers(Utf8JsonWriter w, LearningReport r, bool allFeatures)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
ArgumentNullException.ThrowIfNull(r);
|
||||
w.WriteNumber("schema", LearningReport.SchemaVersion);
|
||||
TimeOrNull(w, "generatedUtc", r.GeneratedUtc);
|
||||
w.WriteString("source", r.Source == LearningSource.Engine ? "engine" : "disk");
|
||||
w.WriteString("engineState", r.EngineState);
|
||||
WriteStatus(w, "status", r.Status);
|
||||
if (r.Dataset is null)
|
||||
{
|
||||
w.WriteNull("dataset");
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WritePropertyName("dataset");
|
||||
WriteDataset(w, r.Dataset);
|
||||
}
|
||||
|
||||
WriteActivation(w, r.Activation);
|
||||
WriteLogistic(w, r.Logistic);
|
||||
if (r.Challenger is { } c)
|
||||
{
|
||||
w.WriteStartObject("challenger");
|
||||
w.WriteNumber("hidden", c.Hidden);
|
||||
w.WriteNumber("seed", c.Seed);
|
||||
w.WriteNumber("seen", c.Seen);
|
||||
Num(w, "outputBias", c.OutputBias);
|
||||
Num(w, "w1Norm", c.W1Norm);
|
||||
Num(w, "w2Norm", c.W2Norm);
|
||||
w.WriteNumber("silentUnits", c.SilentUnits);
|
||||
w.WriteNumber("standardizerRows", c.StandardizerRows);
|
||||
w.WriteBoolean("challengerWins", c.ChallengerWins);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("challenger");
|
||||
}
|
||||
|
||||
if (r.LastCycle is null)
|
||||
{
|
||||
w.WriteNull("lastCycle");
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WritePropertyName("lastCycle");
|
||||
WriteCycle(w, r.LastCycle);
|
||||
}
|
||||
|
||||
WriteRolling(w, r.Rolling);
|
||||
w.WriteStartArray("baskets");
|
||||
foreach (BasketLearningRow b in r.Baskets)
|
||||
{
|
||||
WriteBasket(w, b, allFeatures);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
WriteBandit(w, r.Bandit);
|
||||
if (r.Volatility is { } v)
|
||||
{
|
||||
w.WriteStartObject("volatility");
|
||||
w.WriteNumber("historyCount", v.HistoryCount);
|
||||
Num(w, "tercileLow", v.TercileLow, 10);
|
||||
Num(w, "tercileHigh", v.TercileHigh, 10);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("volatility");
|
||||
}
|
||||
|
||||
WriteKnowledge(w, r.Knowledge);
|
||||
WriteSchedule(w, r.Schedule);
|
||||
w.WriteStartArray("warnings");
|
||||
foreach (string s in r.Warnings)
|
||||
{
|
||||
w.WriteStringValue(s);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
}
|
||||
|
||||
private static void WriteStatus(Utf8JsonWriter w, string name, LearningStatus s)
|
||||
{
|
||||
w.WriteStartObject(name);
|
||||
w.WriteString("mode", s.Mode);
|
||||
w.WriteBoolean("enabled", s.Enabled);
|
||||
w.WriteBoolean("weeklyCycle", s.WeeklyCycle);
|
||||
w.WriteBoolean("challengerEnabled", s.ChallengerEnabled);
|
||||
w.WriteBoolean("activeFlag", s.ActiveFlag);
|
||||
w.WriteBoolean("gateEffective", s.GateEffective);
|
||||
w.WriteString("champion", s.Champion);
|
||||
w.WriteNumber("modelVersion", s.ModelVersion);
|
||||
w.WriteNumber("seen", s.Seen);
|
||||
Num(w, "pMin", s.PMin, 4);
|
||||
Num(w, "deactivationAuc", s.DeactivationAuc, 4);
|
||||
w.WriteString("lastReport", s.LastReport);
|
||||
w.WriteString("reason", s.Reason);
|
||||
w.WriteNumber("trackedEntries", s.TrackedEntries);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
/// <summary>A dataset summary as an object value (the report's <c>dataset</c>, and <c>last_cycle.json</c>).</summary>
|
||||
public static void WriteDataset(Utf8JsonWriter w, DatasetSummary d)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
ArgumentNullException.ThrowIfNull(d);
|
||||
w.WriteStartObject();
|
||||
TimeOrNull(w, "computedUtc", d.ComputedUtc);
|
||||
w.WriteString("datasetHash", d.DatasetHash);
|
||||
w.WriteNumber("closedRows", d.ClosedRows);
|
||||
w.WriteNumber("labelledRows", d.LabelledRows);
|
||||
w.WriteNumber("withoutEntryRow", d.WithoutEntryRow);
|
||||
w.WriteNumber("entryRowsWithoutFeatures", d.EntryRowsWithoutFeatures);
|
||||
w.WriteNumber("loneLegRows", d.LoneLegRows);
|
||||
w.WriteNumber("correctedRows", d.CorrectedRows);
|
||||
w.WriteNumber("unverifiedRows", d.UnverifiedRows);
|
||||
w.WriteNumber("wins", d.Wins);
|
||||
w.WriteNumber("losses", d.Losses);
|
||||
Num(w, "winRate", d.WinRate, 4);
|
||||
w.WriteNumber("pnlNetUsd", Math.Round(double.IsFinite(d.PnlNetUsd) ? d.PnlNetUsd : 0, 2));
|
||||
Num(w, "meanPnlUsd", d.MeanPnlUsd, 2);
|
||||
Num(w, "medianPnlUsd", d.MedianPnlUsd, 2);
|
||||
Num(w, "p5PnlUsd", d.P5PnlUsd, 2);
|
||||
TimeOrNull(w, "firstOpenedUtc", d.FirstOpenedUtc);
|
||||
TimeOrNull(w, "lastClosedUtc", d.LastClosedUtc);
|
||||
w.WriteNumber("demoClosed", d.DemoClosed);
|
||||
w.WriteNumber("activationTarget", d.ActivationTarget);
|
||||
Num(w, "activationProgress", d.ActivationProgress, 4);
|
||||
w.WriteStartArray("byMode");
|
||||
foreach (KeyCount k in d.ByMode)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("key", k.Key);
|
||||
w.WriteNumber("count", k.Count);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
Groups(w, "byBasket", d.ByBasket);
|
||||
Groups(w, "byPreset", d.ByPreset);
|
||||
Groups(w, "byExitReason", d.ByExitReason);
|
||||
w.WriteBoolean("labelsSuspect", d.LabelsSuspect);
|
||||
w.WriteString("labelsSuspectReason", d.LabelsSuspectReason);
|
||||
w.WriteEndObject();
|
||||
|
||||
static void Groups(Utf8JsonWriter w, string name, IReadOnlyList<GroupStats> groups)
|
||||
{
|
||||
w.WriteStartArray(name);
|
||||
foreach (GroupStats g in groups)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("key", g.Key);
|
||||
w.WriteNumber("count", g.Count);
|
||||
Num(w, "winRate", g.WinRate, 4);
|
||||
w.WriteNumber("pnlNetUsd", Math.Round(double.IsFinite(g.PnlNetUsd) ? g.PnlNetUsd : 0, 2));
|
||||
Num(w, "meanPnlUsd", g.MeanPnlUsd, 2);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
}
|
||||
}
|
||||
|
||||
private static void WriteActivation(Utf8JsonWriter w, ActivationChecklist a)
|
||||
{
|
||||
w.WriteStartObject("activation");
|
||||
w.WriteBoolean("passesWalkForward", a.PassesWalkForward);
|
||||
w.WriteBoolean("passesAdr0006", a.PassesAdr0006);
|
||||
w.WriteBoolean("operatorEnabled", a.OperatorEnabled);
|
||||
w.WriteString("motivazione", a.Motivazione);
|
||||
w.WriteStartArray("items");
|
||||
foreach (ActivationItem i in a.Items)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("key", i.Key);
|
||||
w.WriteString("label", i.Label);
|
||||
w.WriteString("current", i.Current);
|
||||
w.WriteString("required", i.Required);
|
||||
if (i.Ok is { } ok)
|
||||
{
|
||||
w.WriteBoolean("ok", ok);
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("ok");
|
||||
}
|
||||
|
||||
w.WriteString("source", i.Source);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
private static void WriteLogistic(Utf8JsonWriter w, LogisticSummary l)
|
||||
{
|
||||
w.WriteStartObject("logistic");
|
||||
w.WriteNumber("inputs", l.Inputs);
|
||||
w.WriteNumber("seen", l.Seen);
|
||||
Num(w, "learningRate0", l.LearningRate0, 8);
|
||||
Num(w, "currentLearningRate", l.CurrentLearningRate, 8);
|
||||
Num(w, "l2", l.L2, 8);
|
||||
Num(w, "bias", l.Bias);
|
||||
Num(w, "weightNorm", l.WeightNorm);
|
||||
w.WriteNumber("standardizerRows", l.StandardizerRows);
|
||||
Num(w, "standardizerHalfLifeRows", l.StandardizerHalfLifeRows, 3);
|
||||
w.WriteStartArray("weights");
|
||||
foreach (FeatureWeight f in l.Weights)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("index", f.Index);
|
||||
w.WriteString("name", f.Name);
|
||||
w.WriteString("label", f.Label);
|
||||
Num(w, "weight", f.Weight);
|
||||
Num(w, "mean", f.Mean, 8);
|
||||
Num(w, "stdDev", f.StdDev, 8);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
/// <summary>A cycle summary as an object value (the report's <c>lastCycle</c>, and <c>last_cycle.json</c>).</summary>
|
||||
public static void WriteCycle(Utf8JsonWriter w, CycleSummary c)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
ArgumentNullException.ThrowIfNull(c);
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("version", c.Version);
|
||||
TimeOrNull(w, "utc", c.Utc);
|
||||
w.WriteNumber("durationMs", c.DurationMs);
|
||||
w.WriteString("trigger", c.Trigger);
|
||||
w.WriteNumber("rows", c.Rows);
|
||||
w.WriteString("datasetHash", c.DatasetHash);
|
||||
TimeOrNull(w, "trainedOnUntilUtc", c.TrainedOnUntilUtc);
|
||||
w.WritePropertyName("logistic");
|
||||
WriteEvaluation(w, c.Logistic);
|
||||
if (c.Mlp is null)
|
||||
{
|
||||
w.WriteNull("mlp");
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WritePropertyName("mlp");
|
||||
WriteEvaluation(w, c.Mlp);
|
||||
}
|
||||
|
||||
w.WriteBoolean("challengerWins", c.ChallengerWins);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
private static void WriteEvaluation(Utf8JsonWriter w, ModelEvaluation e)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("model", e.Model);
|
||||
w.WriteNumber("rows", e.Rows);
|
||||
w.WriteNumber("burnIn", e.BurnIn);
|
||||
Num(w, "auc", e.Auc);
|
||||
Num(w, "aucLow", e.AucLow);
|
||||
Num(w, "aucHigh", e.AucHigh);
|
||||
Num(w, "brier", e.Brier);
|
||||
Num(w, "logLoss", e.LogLoss);
|
||||
Calibration(w, "calibration", e.Calibration);
|
||||
w.WriteNumber("pnlAllUsd", Math.Round(double.IsFinite(e.PnlAllUsd) ? e.PnlAllUsd : 0, 2));
|
||||
w.WriteNumber("pnlFilteredUsd", Math.Round(double.IsFinite(e.PnlFilteredUsd) ? e.PnlFilteredUsd : 0, 2));
|
||||
w.WriteNumber("filteredCount", e.FilteredCount);
|
||||
Num(w, "sharpeAll", e.SharpeAll);
|
||||
Num(w, "sharpeFiltered", e.SharpeFiltered);
|
||||
Num(w, "dsrFiltered", e.DsrFiltered);
|
||||
w.WriteBoolean("passesActivation", e.PassesActivation);
|
||||
w.WriteString("motivazione", e.Motivazione);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
private static void Calibration(Utf8JsonWriter w, string name, IReadOnlyList<CalibrationBin> bins)
|
||||
{
|
||||
w.WriteStartArray(name);
|
||||
foreach (CalibrationBin b in bins)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
Num(w, "lower", b.Lower, 4);
|
||||
Num(w, "upper", b.Upper, 4);
|
||||
w.WriteNumber("count", b.Count);
|
||||
Num(w, "meanPredicted", b.MeanPredicted);
|
||||
Num(w, "observedRate", b.ObservedRate);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
}
|
||||
|
||||
private static void WriteRolling(Utf8JsonWriter w, RollingPerformance r)
|
||||
{
|
||||
w.WriteStartObject("rolling");
|
||||
w.WriteNumber("count", r.Count);
|
||||
w.WriteString("pAt", r.PAt);
|
||||
Num(w, "auc100", r.Auc100);
|
||||
Num(w, "auc200", r.Auc200);
|
||||
Num(w, "auc100Low", r.Auc100Low);
|
||||
Num(w, "auc100High", r.Auc100High);
|
||||
Num(w, "brier100", r.Brier100);
|
||||
Num(w, "logLoss100", r.LogLoss100);
|
||||
Num(w, "hitRate100", r.HitRate100);
|
||||
Num(w, "meanP100", r.MeanP100);
|
||||
Num(w, "lastOutcomes10", r.LastOutcomes10);
|
||||
w.WriteStartArray("recentP");
|
||||
foreach (double p in r.RecentP)
|
||||
{
|
||||
NumValue(w, p, 4);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteStartArray("recentLabel");
|
||||
foreach (int y in r.RecentLabel)
|
||||
{
|
||||
w.WriteNumberValue(y);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteStartArray("aucHistory");
|
||||
foreach (AucPoint p in r.AucHistory)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
TimeOrNull(w, "utc", p.Utc);
|
||||
Num(w, "auc100", p.Auc100, 4);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
Calibration(w, "calibration", r.Calibration);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
private static void WriteBasket(Utf8JsonWriter w, BasketLearningRow b, bool allFeatures)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("basket", b.Basket);
|
||||
w.WriteString("cross", b.Cross);
|
||||
w.WriteBoolean("enabled", b.Enabled);
|
||||
w.WriteString("state", b.State);
|
||||
Num(w, "pMl", b.PMl, 4);
|
||||
TimeOrNull(w, "pMlUtc", b.PMlUtc);
|
||||
w.WriteString("pMlKind", b.PMlKind);
|
||||
Num(w, "intercept", b.Intercept, 6);
|
||||
w.WriteBoolean("wouldBeFiltered", b.WouldBeFiltered);
|
||||
Features(w, "topContributions", b.TopContributions);
|
||||
if (allFeatures)
|
||||
{
|
||||
Features(w, "features", b.Features);
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("features");
|
||||
}
|
||||
|
||||
if (b.Vol is { } v)
|
||||
{
|
||||
w.WriteStartObject("vol");
|
||||
w.WriteNumber("bars", v.Bars);
|
||||
w.WriteString("activeModel", v.ActiveModel);
|
||||
Num(w, "ewmaSigma", v.EwmaSigma, 10);
|
||||
Num(w, "harSigma", v.HarSigma, 10);
|
||||
Num(w, "forecastSigma", v.ForecastSigma, 10);
|
||||
Num(w, "average30dSigma", v.Average30dSigma, 10);
|
||||
Num(w, "volRatio", v.VolRatio, 4);
|
||||
Num(w, "zInScale", v.ZInScale, 4);
|
||||
Num(w, "rmseEwma", v.RmseEwma, 10);
|
||||
Num(w, "rmseHar", v.RmseHar, 10);
|
||||
w.WriteNumber("scored", v.Scored);
|
||||
w.WriteNumber("pending", v.Pending);
|
||||
TimeOrNull(w, "lastHarFitUtc", v.LastHarFitUtc);
|
||||
w.WriteNumber("context", v.Context);
|
||||
w.WriteString("contextLabel", v.ContextLabel);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("vol");
|
||||
}
|
||||
|
||||
w.WriteEndObject();
|
||||
|
||||
static void Features(Utf8JsonWriter w, string name, IReadOnlyList<FeatureValue> values)
|
||||
{
|
||||
w.WriteStartArray(name);
|
||||
foreach (FeatureValue f in values)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("index", f.Index);
|
||||
w.WriteString("name", f.Name);
|
||||
w.WriteString("label", f.Label);
|
||||
Num(w, "value", f.Value);
|
||||
Num(w, "z", f.Z, 4);
|
||||
Num(w, "contribution", f.Contribution);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
}
|
||||
}
|
||||
|
||||
private static void WriteBandit(Utf8JsonWriter w, BanditSummary b)
|
||||
{
|
||||
w.WriteStartObject("bandit");
|
||||
w.WriteNumber("contexts", b.Contexts);
|
||||
Num(w, "explorationCap", b.ExplorationCap, 4);
|
||||
w.WriteNumber("choices", b.Choices);
|
||||
w.WriteNumber("explorations", b.Explorations);
|
||||
Num(w, "explorationShare", b.ExplorationShare, 4);
|
||||
w.WriteString("currentPreset", b.CurrentPreset);
|
||||
w.WriteBoolean("applied", false);
|
||||
w.WriteBoolean("rewardsSuspect", b.RewardsSuspect);
|
||||
w.WriteStartArray("arms");
|
||||
foreach (BanditArm a in b.Arms)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("context", a.Context);
|
||||
w.WriteString("contextLabel", a.ContextLabel);
|
||||
w.WriteString("preset", a.Preset);
|
||||
Num(w, "alpha", a.Alpha, 4);
|
||||
Num(w, "beta", a.Beta, 4);
|
||||
w.WriteNumber("successes", a.Successes);
|
||||
w.WriteNumber("failures", a.Failures);
|
||||
w.WriteNumber("n", a.N);
|
||||
Num(w, "mean", a.Mean, 4);
|
||||
Num(w, "low95", a.Low95, 4);
|
||||
Num(w, "high95", a.High95, 4);
|
||||
w.WriteBoolean("bestInContext", a.BestInContext);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
if (b.LastProposal is { } p)
|
||||
{
|
||||
w.WriteStartObject("lastProposal");
|
||||
TimeOrNull(w, "utc", p.Utc);
|
||||
w.WriteNumber("context", p.Context);
|
||||
w.WriteString("preset", p.Preset);
|
||||
w.WriteBoolean("explored", p.Explored);
|
||||
w.WriteStartArray("means");
|
||||
foreach (double m in p.Means)
|
||||
{
|
||||
NumValue(w, m, 4);
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteString("text", p.Text);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("lastProposal");
|
||||
}
|
||||
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
private static void WriteKnowledge(Utf8JsonWriter w, KnowledgeSnapshot k)
|
||||
{
|
||||
w.WriteStartObject("knowledge");
|
||||
w.WriteStartArray("calibration");
|
||||
foreach (CalibrationTableRow c in k.Calibration)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("dimension", c.Dimension);
|
||||
w.WriteString("bucket", c.Bucket);
|
||||
w.WriteNumber("count", c.Count);
|
||||
Num(w, "winRate", c.WinRate, 4);
|
||||
Num(w, "meanPnl", c.MeanPnl, 2);
|
||||
Num(w, "totalPnl", c.TotalPnl, 2);
|
||||
w.WriteString("motivazione", c.Motivazione);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteStartArray("proposals");
|
||||
foreach (ProposalRow p in k.Proposals)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
TimeOrNull(w, "utc", p.Utc);
|
||||
w.WriteString("origin", p.Origin);
|
||||
w.WriteString("parameter", p.Parameter);
|
||||
w.WriteString("currentValue", p.CurrentValue);
|
||||
w.WriteString("proposedValue", p.ProposedValue);
|
||||
w.WriteString("evidence", p.Evidence);
|
||||
w.WriteString("state", p.State);
|
||||
w.WriteString("motivazione", p.Motivazione);
|
||||
w.WriteBoolean("basedOnSuspectData", p.BasedOnSuspectData);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteStartArray("registry");
|
||||
foreach (RegistryRow r in k.Registry)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("version", r.Version);
|
||||
TimeOrNull(w, "utc", r.Utc);
|
||||
w.WriteString("type", r.Type);
|
||||
w.WriteNumber("nTrain", r.NTrain);
|
||||
Num(w, "aucWf", r.AucWf, 4);
|
||||
Num(w, "brier", r.Brier, 4);
|
||||
Num(w, "logLoss", r.LogLoss, 4);
|
||||
w.WriteString("state", r.State);
|
||||
w.WriteString("motivazione", r.Motivazione);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
if (k.Insights is { } i)
|
||||
{
|
||||
w.WriteStartObject("insights");
|
||||
w.WriteString("fileName", i.FileName);
|
||||
TimeOrNull(w, "modifiedUtc", i.ModifiedUtc);
|
||||
w.WriteString("markdown", i.Markdown);
|
||||
w.WriteBoolean("truncated", i.Truncated);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("insights");
|
||||
}
|
||||
|
||||
w.WriteStartArray("modelFiles");
|
||||
foreach (ModelFileRow m in k.ModelFiles)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("name", m.Name);
|
||||
w.WriteNumber("bytes", m.Bytes);
|
||||
TimeOrNull(w, "modifiedUtc", m.ModifiedUtc);
|
||||
w.WriteString("kind", m.Kind);
|
||||
IntOrNull(w, "version", m.Version);
|
||||
IntOrNull(w, "rows", m.Rows);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteStartArray("files");
|
||||
foreach (FileRow f in k.Files)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteString("name", f.Name);
|
||||
w.WriteNumber("bytes", f.Bytes);
|
||||
TimeOrNull(w, "modifiedUtc", f.ModifiedUtc);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
private static void WriteSchedule(Utf8JsonWriter w, CycleSchedule s)
|
||||
{
|
||||
w.WriteStartObject("schedule");
|
||||
TimeOrNull(w, "lastCycleUtc", s.LastCycleUtc);
|
||||
TimeOrNull(w, "nextDueUtc", s.NextDueUtc);
|
||||
w.WriteBoolean("runsInBot", s.RunsInBot);
|
||||
w.WriteBoolean("due", s.Due);
|
||||
w.WriteBoolean("running", s.Running);
|
||||
TimeOrNull(w, "runningSinceUtc", s.RunningSinceUtc);
|
||||
w.WriteString("runningPhase", s.RunningPhase);
|
||||
if (s.LastDurationMs is { } d)
|
||||
{
|
||||
w.WriteNumber("lastDurationMs", d);
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull("lastDurationMs");
|
||||
}
|
||||
|
||||
w.WriteString("lastError", s.LastError);
|
||||
w.WriteString("lastTrigger", s.LastTrigger);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// data/models/last_cycle.json
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
/// <summary>The file that keeps the last cycle's evaluation and dataset (they were thrown away until 5.0); a cycle without rows keeps only its dataset.</summary>
|
||||
public static string CycleFile(CycleSummary? cycle, DatasetSummary? dataset, DateTime savedUtc)
|
||||
{
|
||||
using MemoryStream ms = new();
|
||||
using (Utf8JsonWriter w = new(ms, new JsonWriterOptions { Indented = true, Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping }))
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("schema", CycleFileSchema);
|
||||
TimeOrNull(w, "savedUtc", savedUtc);
|
||||
if (cycle is null)
|
||||
{
|
||||
w.WriteNull("cycle");
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WritePropertyName("cycle");
|
||||
WriteCycle(w, cycle);
|
||||
}
|
||||
if (dataset is null)
|
||||
{
|
||||
w.WriteNull("dataset");
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WritePropertyName("dataset");
|
||||
WriteDataset(w, dataset);
|
||||
}
|
||||
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
return System.Text.Encoding.UTF8.GetString(ms.ToArray());
|
||||
}
|
||||
|
||||
/// <summary>Reads <c>last_cycle.json</c>; false when the text is not one (the caller keeps what it had).</summary>
|
||||
public static bool TryReadCycleFile(string json, out CycleSummary? cycle, out DatasetSummary? dataset)
|
||||
{
|
||||
cycle = null;
|
||||
dataset = null;
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(json);
|
||||
JsonElement root = doc.RootElement;
|
||||
if (root.ValueKind != JsonValueKind.Object)
|
||||
{
|
||||
return false;
|
||||
}
|
||||
|
||||
if (root.TryGetProperty("cycle", out JsonElement c) && c.ValueKind == JsonValueKind.Object)
|
||||
{
|
||||
cycle = ReadCycle(c);
|
||||
}
|
||||
|
||||
if (root.TryGetProperty("dataset", out JsonElement d) && d.ValueKind == JsonValueKind.Object)
|
||||
{
|
||||
dataset = ReadDataset(d);
|
||||
}
|
||||
|
||||
return cycle is not null || dataset is not null;
|
||||
}
|
||||
catch (Exception ex) when (ex is JsonException or InvalidOperationException or FormatException or KeyNotFoundException)
|
||||
{
|
||||
cycle = null;
|
||||
dataset = null;
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
public static CycleSummary ReadCycle(JsonElement c)
|
||||
{
|
||||
ModelEvaluation logistic = ReadEvaluation(c.GetProperty("logistic"));
|
||||
ModelEvaluation? mlp = c.TryGetProperty("mlp", out JsonElement m) && m.ValueKind == JsonValueKind.Object ? ReadEvaluation(m) : null;
|
||||
return new CycleSummary(I(c, "version"), T(c, "utc") ?? DateTime.MinValue, L(c, "durationMs"), S(c, "trigger"), I(c, "rows"), S(c, "datasetHash"),
|
||||
T(c, "trainedOnUntilUtc"), logistic, mlp, B(c, "challengerWins"));
|
||||
}
|
||||
|
||||
private static ModelEvaluation ReadEvaluation(JsonElement e) => new(
|
||||
S(e, "model"), I(e, "rows"), I(e, "burnIn"), D(e, "auc"), D(e, "aucLow"), D(e, "aucHigh"), D(e, "brier"), D(e, "logLoss"), Bins(e, "calibration"),
|
||||
D(e, "pnlAllUsd"), D(e, "pnlFilteredUsd"), I(e, "filteredCount"), D(e, "sharpeAll"), D(e, "sharpeFiltered"), D(e, "dsrFiltered"), B(e, "passesActivation"), S(e, "motivazione"));
|
||||
|
||||
public static DatasetSummary ReadDataset(JsonElement d) => new(
|
||||
T(d, "computedUtc") ?? DateTime.MinValue, S(d, "datasetHash"), I(d, "closedRows"), I(d, "labelledRows"), I(d, "withoutEntryRow"), I(d, "entryRowsWithoutFeatures"),
|
||||
I(d, "loneLegRows"), I(d, "correctedRows"), I(d, "unverifiedRows"), I(d, "wins"), I(d, "losses"), D(d, "winRate"), D(d, "pnlNetUsd"), D(d, "meanPnlUsd"),
|
||||
D(d, "medianPnlUsd"), D(d, "p5PnlUsd"), T(d, "firstOpenedUtc"), T(d, "lastClosedUtc"), I(d, "demoClosed"), I(d, "activationTarget"), D(d, "activationProgress"),
|
||||
[.. Items(d, "byMode").Select(static k => new KeyCount(S(k, "key"), I(k, "count")))],
|
||||
Groups(d, "byBasket"), Groups(d, "byPreset"), Groups(d, "byExitReason"), B(d, "labelsSuspect"), S(d, "labelsSuspectReason"));
|
||||
|
||||
private static List<GroupStats> Groups(JsonElement e, string name) =>
|
||||
[.. Items(e, name).Select(static g => new GroupStats(S(g, "key"), I(g, "count"), D(g, "winRate"), D(g, "pnlNetUsd"), D(g, "meanPnlUsd")))];
|
||||
|
||||
private static List<CalibrationBin> Bins(JsonElement e, string name) =>
|
||||
[.. Items(e, name).Select(static b => new CalibrationBin(D(b, "lower"), D(b, "upper"), I(b, "count"), D(b, "meanPredicted"), D(b, "observedRate")))];
|
||||
|
||||
private static IEnumerable<JsonElement> Items(JsonElement e, string name) =>
|
||||
e.TryGetProperty(name, out JsonElement a) && a.ValueKind == JsonValueKind.Array ? a.EnumerateArray() : [];
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Helpers
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
/// <summary>A number rounded to <paramref name="decimals"/>, or null when not finite.</summary>
|
||||
public static void Num(Utf8JsonWriter w, string name, double v, int decimals = 6)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
if (double.IsFinite(v))
|
||||
{
|
||||
w.WriteNumber(name, Math.Round(v, decimals));
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull(name);
|
||||
}
|
||||
}
|
||||
|
||||
private static void NumValue(Utf8JsonWriter w, double v, int decimals)
|
||||
{
|
||||
if (double.IsFinite(v))
|
||||
{
|
||||
w.WriteNumberValue(Math.Round(v, decimals));
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNullValue();
|
||||
}
|
||||
}
|
||||
|
||||
private static void IntOrNull(Utf8JsonWriter w, string name, int? v)
|
||||
{
|
||||
if (v is { } x)
|
||||
{
|
||||
w.WriteNumber(name, x);
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull(name);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>An ISO-8601 UTC time, or null when unknown.</summary>
|
||||
public static void TimeOrNull(Utf8JsonWriter w, string name, DateTime? t)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(w);
|
||||
if (t is { } v && v != default && v != DateTime.MinValue)
|
||||
{
|
||||
w.WriteString(name, DateTime.SpecifyKind(v, DateTimeKind.Utc).ToString("O", CultureInfo.InvariantCulture));
|
||||
}
|
||||
else
|
||||
{
|
||||
w.WriteNull(name);
|
||||
}
|
||||
}
|
||||
|
||||
private static string S(JsonElement e, string name) => e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.String ? v.GetString() ?? string.Empty : string.Empty;
|
||||
|
||||
private static double D(JsonElement e, string name) => e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.Number ? v.GetDouble() : double.NaN;
|
||||
|
||||
private static int I(JsonElement e, string name) => e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.Number && v.TryGetInt32(out int i) ? i : 0;
|
||||
|
||||
private static long L(JsonElement e, string name) => e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.Number && v.TryGetInt64(out long l) ? l : 0;
|
||||
|
||||
private static bool B(JsonElement e, string name) => e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.True;
|
||||
|
||||
private static DateTime? T(JsonElement e, string name) =>
|
||||
e.TryGetProperty(name, out JsonElement v) && v.ValueKind == JsonValueKind.String &&
|
||||
DateTime.TryParse(v.GetString(), CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out DateTime t) ? t : null;
|
||||
}
|
||||
@@ -0,0 +1,441 @@
|
||||
using Encelado.Core.Ml;
|
||||
|
||||
namespace Encelado.Core.Baskets.Learning;
|
||||
|
||||
/// <summary>Where a learning report comes from: the running engine's published picture, or the files of a stopped one.</summary>
|
||||
public enum LearningSource
|
||||
{
|
||||
Engine = 0,
|
||||
Disk,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The learning page (5.1, <c>GET /api/learning</c>, docs/API.md): what the learning stack
|
||||
/// knows and what it has learnt, in one immutable picture. Pure data — times UTC, amounts
|
||||
/// USD, NaN (or null) where a number is unknown — built by the engine thread (the live
|
||||
/// part) and by a read-only reader of the files (a stopped engine, the knowledge base).
|
||||
/// </summary>
|
||||
public sealed record LearningReport
|
||||
{
|
||||
public const int SchemaVersion = 1;
|
||||
|
||||
public required DateTime GeneratedUtc { get; init; }
|
||||
|
||||
public required LearningSource Source { get; init; }
|
||||
|
||||
/// <summary>The supervisor's word: <c>running</c>, <c>stopped</c>, <c>faulted</c>…</summary>
|
||||
public required string EngineState { get; init; }
|
||||
|
||||
public required LearningStatus Status { get; init; }
|
||||
|
||||
/// <summary>The training set as of its last computation; null before the ledger was ever read.</summary>
|
||||
public DatasetSummary? Dataset { get; init; }
|
||||
|
||||
public required ActivationChecklist Activation { get; init; }
|
||||
|
||||
public required LogisticSummary Logistic { get; init; }
|
||||
|
||||
/// <summary>The MLP challenger; null when there is none (not trained, or switched off).</summary>
|
||||
public MlpSummary? Challenger { get; init; }
|
||||
|
||||
/// <summary>The last cycle's evaluation; null before the first cycle.</summary>
|
||||
public CycleSummary? LastCycle { get; init; }
|
||||
|
||||
public required RollingPerformance Rolling { get; init; }
|
||||
|
||||
public IReadOnlyList<BasketLearningRow> Baskets { get; init; } = [];
|
||||
|
||||
public required BanditSummary Bandit { get; init; }
|
||||
|
||||
public VolatilityContextSummary? Volatility { get; init; }
|
||||
|
||||
public required KnowledgeSnapshot Knowledge { get; init; }
|
||||
|
||||
public required CycleSchedule Schedule { get; init; }
|
||||
|
||||
/// <summary>Plain Italian sentences: what the operator should know about the data or the models.</summary>
|
||||
public IReadOnlyList<string> Warnings { get; init; } = [];
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The part of the report that describes the models and the baskets: what a running engine
|
||||
/// publishes after every bar close, basket close, cycle and command (and every minute), and
|
||||
/// what the disk reader rebuilds from the files of a stopped engine. Immutable.
|
||||
/// </summary>
|
||||
public sealed record LearningLiveReport
|
||||
{
|
||||
/// <summary>A number that grows with every publication (0 for a picture read from disk).</summary>
|
||||
public long Version { get; init; }
|
||||
|
||||
public required DateTime BuiltUtc { get; init; }
|
||||
|
||||
public required LearningStatus Status { get; init; }
|
||||
|
||||
public DatasetSummary? Dataset { get; init; }
|
||||
|
||||
public required LogisticSummary Logistic { get; init; }
|
||||
|
||||
public MlpSummary? Challenger { get; init; }
|
||||
|
||||
public CycleSummary? LastCycle { get; init; }
|
||||
|
||||
public required RollingPerformance Rolling { get; init; }
|
||||
|
||||
public IReadOnlyList<BasketLearningRow> Baskets { get; init; } = [];
|
||||
|
||||
public required BanditSummary Bandit { get; init; }
|
||||
|
||||
public VolatilityContextSummary? Volatility { get; init; }
|
||||
|
||||
public required CycleSchedule Schedule { get; init; }
|
||||
|
||||
public IReadOnlyList<string> Warnings { get; init; } = [];
|
||||
|
||||
/// <summary>When the models taught by the proceeds-based labels of 4.0.0–5.0.0 were retired; null when never.</summary>
|
||||
public DateTime? LabelsFixedUtc { get; init; }
|
||||
|
||||
/// <summary>Labelled baskets as the training set counts them, with their entry features (the tick's headline, against the 300 of the activation; the dataset's <c>labelledRows</c>).</summary>
|
||||
public int LabelledRows { get; init; }
|
||||
|
||||
/// <summary>The volatility model in use on the first enabled basket (<c>EWMA</c> or <c>HAR</c>).</summary>
|
||||
public string VolModel { get; init; } = "EWMA";
|
||||
}
|
||||
|
||||
/// <summary>What state the meta-model is in and why.</summary>
|
||||
public sealed record LearningStatus(
|
||||
string Mode,
|
||||
bool Enabled,
|
||||
bool WeeklyCycle,
|
||||
bool ChallengerEnabled,
|
||||
bool ActiveFlag,
|
||||
bool GateEffective,
|
||||
string Champion,
|
||||
int ModelVersion,
|
||||
int Seen,
|
||||
double PMin,
|
||||
double DeactivationAuc,
|
||||
string LastReport,
|
||||
string Reason,
|
||||
int TrackedEntries)
|
||||
{
|
||||
public const string ShadowDisabled = "ombra-disabilitato";
|
||||
public const string Shadow = "ombra";
|
||||
public const string Active = "attivo";
|
||||
|
||||
/// <summary>The mode word: learning off (ADR-0006), shadow, or filtering the entries.</summary>
|
||||
public static string ModeOf(bool enabled, bool active) => !enabled ? ShadowDisabled : active ? Active : Shadow;
|
||||
|
||||
/// <summary>Why the meta-model is in its state, for the operator.</summary>
|
||||
public static string ReasonOf(bool enabled, bool active, double pMin, CycleSummary? lastCycle)
|
||||
{
|
||||
if (!enabled)
|
||||
{
|
||||
return "apprendimento spento in Impostazioni ▸ Strategia (ADR-0006): la logistica resta in ombra, impara a ogni chiusura ma non filtra mai gli ingressi";
|
||||
}
|
||||
|
||||
if (active)
|
||||
{
|
||||
return string.Create(System.Globalization.CultureInfo.InvariantCulture,
|
||||
$"attivazione superata all'ultimo ciclo: gli ingressi con p_ML sotto {pMin:0.00} vengono rifiutati; torna in ombra se l'AUC mobile su 100 basket scende sotto {ModelEvaluator.DeactivationAuc:0.00}");
|
||||
}
|
||||
|
||||
return lastCycle is null
|
||||
? "nessun ciclo eseguito: l'attivazione si valuta al ciclo (settimanale nel bot o «Esegui ciclo»)"
|
||||
: $"resta in ombra: {lastCycle.Logistic.Motivazione}";
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>A count per key (modes of the dataset).</summary>
|
||||
public sealed record KeyCount(string Key, int Count);
|
||||
|
||||
/// <summary>Counts and P&L of a group of labelled baskets.</summary>
|
||||
public sealed record GroupStats(string Key, int Count, double WinRate, double PnlNetUsd, double MeanPnlUsd);
|
||||
|
||||
/// <summary>The training set: the closed baskets of <c>baskets.csv</c> (corrected) joined with their entry features.</summary>
|
||||
public sealed record DatasetSummary(
|
||||
DateTime ComputedUtc,
|
||||
string DatasetHash,
|
||||
int ClosedRows,
|
||||
int LabelledRows,
|
||||
int WithoutEntryRow,
|
||||
int EntryRowsWithoutFeatures,
|
||||
int LoneLegRows,
|
||||
int CorrectedRows,
|
||||
int UnverifiedRows,
|
||||
int Wins,
|
||||
int Losses,
|
||||
double WinRate,
|
||||
double PnlNetUsd,
|
||||
double MeanPnlUsd,
|
||||
double MedianPnlUsd,
|
||||
double P5PnlUsd,
|
||||
DateTime? FirstOpenedUtc,
|
||||
DateTime? LastClosedUtc,
|
||||
int DemoClosed,
|
||||
int ActivationTarget,
|
||||
double ActivationProgress,
|
||||
IReadOnlyList<KeyCount> ByMode,
|
||||
IReadOnlyList<GroupStats> ByBasket,
|
||||
IReadOnlyList<GroupStats> ByPreset,
|
||||
IReadOnlyList<GroupStats> ByExitReason,
|
||||
bool LabelsSuspect,
|
||||
string LabelsSuspectReason);
|
||||
|
||||
/// <summary>One condition of the activation, with its value and requirement as text; <see cref="Ok"/> null = not evaluated.</summary>
|
||||
public sealed record ActivationItem(string Key, string Label, string Current, string Required, bool? Ok, string Source);
|
||||
|
||||
/// <summary>Everything the activation of the gate depends on (§8.3 and ADR-0006).</summary>
|
||||
public sealed record ActivationChecklist(bool PassesWalkForward, bool PassesAdr0006, bool OperatorEnabled, string Motivazione, IReadOnlyList<ActivationItem> Items);
|
||||
|
||||
/// <summary>One weight of the logistic, on standardised features, with the standardiser's statistics of its feature.</summary>
|
||||
public sealed record FeatureWeight(int Index, string Name, string Label, double Weight, double Mean, double StdDev);
|
||||
|
||||
/// <summary>The logistic regression (level 1): hyper-parameters, weights by decreasing |w|, standardiser.</summary>
|
||||
public sealed record LogisticSummary(
|
||||
int Inputs,
|
||||
int Seen,
|
||||
double LearningRate0,
|
||||
double CurrentLearningRate,
|
||||
double L2,
|
||||
double Bias,
|
||||
double WeightNorm,
|
||||
long StandardizerRows,
|
||||
double StandardizerHalfLifeRows,
|
||||
IReadOnlyList<FeatureWeight> Weights);
|
||||
|
||||
/// <summary>The MLP challenger (level 2).</summary>
|
||||
public sealed record MlpSummary(int Hidden, int Seed, int Seen, double OutputBias, double W1Norm, double W2Norm, int SilentUnits, long StandardizerRows, bool ChallengerWins);
|
||||
|
||||
/// <summary>A walk-forward evaluation of one model, as the activation rule looks at it.</summary>
|
||||
public sealed record ModelEvaluation(
|
||||
string Model,
|
||||
int Rows,
|
||||
int BurnIn,
|
||||
double Auc,
|
||||
double AucLow,
|
||||
double AucHigh,
|
||||
double Brier,
|
||||
double LogLoss,
|
||||
IReadOnlyList<CalibrationBin> Calibration,
|
||||
double PnlAllUsd,
|
||||
double PnlFilteredUsd,
|
||||
int FilteredCount,
|
||||
double SharpeAll,
|
||||
double SharpeFiltered,
|
||||
double DsrFiltered,
|
||||
bool PassesActivation,
|
||||
string Motivazione)
|
||||
{
|
||||
public static ModelEvaluation From(ModelReport r, int burnIn)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(r);
|
||||
return new ModelEvaluation(r.Model, r.Rows, burnIn, r.Auc, r.AucLow, r.AucHigh, r.Brier, r.LogLoss, [.. r.Calibration], r.PnlAll, r.PnlFiltered,
|
||||
r.FilteredCount, r.SharpeAll, r.SharpeFiltered, r.DsrFiltered, r.PassesActivation, r.Motivazione);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>What a cycle of the learning stack did (retained in <c>data/models/last_cycle.json</c>).</summary>
|
||||
public sealed record CycleSummary(
|
||||
int Version,
|
||||
DateTime Utc,
|
||||
long DurationMs,
|
||||
string Trigger,
|
||||
int Rows,
|
||||
string DatasetHash,
|
||||
DateTime? TrainedOnUntilUtc,
|
||||
ModelEvaluation Logistic,
|
||||
ModelEvaluation? Mlp,
|
||||
bool ChallengerWins);
|
||||
|
||||
/// <summary>The words of the cycle's trigger.</summary>
|
||||
public static class CycleTriggers
|
||||
{
|
||||
public const string Weekly = "settimanale";
|
||||
public const string Manual = "manuale";
|
||||
public const string Offline = "offline";
|
||||
}
|
||||
|
||||
/// <summary>One point of the rolling AUC over time.</summary>
|
||||
public sealed record AucPoint(DateTime Utc, double Auc100);
|
||||
|
||||
/// <summary>How the probabilities given at entry fared once the baskets closed (the deactivation guard).</summary>
|
||||
public sealed record RollingPerformance(
|
||||
int Count,
|
||||
string PAt,
|
||||
double Auc100,
|
||||
double Auc200,
|
||||
double Auc100Low,
|
||||
double Auc100High,
|
||||
double Brier100,
|
||||
double LogLoss100,
|
||||
double HitRate100,
|
||||
double MeanP100,
|
||||
double LastOutcomes10,
|
||||
IReadOnlyList<double> RecentP,
|
||||
IReadOnlyList<int> RecentLabel,
|
||||
IReadOnlyList<AucPoint> AucHistory,
|
||||
IReadOnlyList<CalibrationBin> Calibration)
|
||||
{
|
||||
public const string AtEntry = "entry";
|
||||
|
||||
public static readonly RollingPerformance Empty = new(0, AtEntry, double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, [], [], [], []);
|
||||
}
|
||||
|
||||
/// <summary>One feature of a basket's vector: its value, its standardised value and what it adds to the logit (<c>w·z</c>).</summary>
|
||||
public sealed record FeatureValue(int Index, string Name, string Label, double Value, double Z, double Contribution);
|
||||
|
||||
/// <summary>The volatility forecaster of one basket.</summary>
|
||||
public sealed record BasketVolRow(
|
||||
int Bars,
|
||||
string ActiveModel,
|
||||
double EwmaSigma,
|
||||
double HarSigma,
|
||||
double ForecastSigma,
|
||||
double Average30dSigma,
|
||||
double VolRatio,
|
||||
double ZInScale,
|
||||
double RmseEwma,
|
||||
double RmseHar,
|
||||
int Scored,
|
||||
int Pending,
|
||||
DateTime? LastHarFitUtc,
|
||||
int Context,
|
||||
string ContextLabel);
|
||||
|
||||
/// <summary>
|
||||
/// One basket as the meta-model sees it. The contributions explain the probability shown (5.1
|
||||
/// review): they come from the model that gave <see cref="PMl"/>, at the moment it gave it, so
|
||||
/// their sum plus <see cref="Intercept"/> is the logit of <see cref="PMl"/>. A probability no
|
||||
/// stored explanation goes with (an entry remembered by an older version, a model that moved
|
||||
/// since) is shown without contributions.
|
||||
/// </summary>
|
||||
public sealed record BasketLearningRow(
|
||||
string Basket,
|
||||
string Cross,
|
||||
bool Enabled,
|
||||
string State,
|
||||
double PMl,
|
||||
DateTime? PMlUtc,
|
||||
string PMlKind,
|
||||
bool WouldBeFiltered,
|
||||
IReadOnlyList<FeatureValue> TopContributions,
|
||||
IReadOnlyList<FeatureValue> Features,
|
||||
BasketVolRow? Vol)
|
||||
{
|
||||
/// <summary>The engine's probability at the last bar close of a basket without a position.</summary>
|
||||
public const string KindLastBar = "ultima barra";
|
||||
|
||||
/// <summary>The probability given at the entry of the open basket.</summary>
|
||||
public const string KindAtEntry = "all'ingresso";
|
||||
|
||||
/// <summary>A stopped bot's page: the saved model's probability for the values of the last evaluation row, which the model of that bar no longer is.</summary>
|
||||
public const string KindRecomputed = "ricalcolata con il modello di oggi";
|
||||
|
||||
/// <summary>The intercept of the model that gave <see cref="PMl"/>; NaN without contributions.</summary>
|
||||
public double Intercept { get; init; } = double.NaN;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A probability with what made it, from one model at one moment (5.1 review): the features'
|
||||
/// contributions (<c>w·z</c>, in index order) and the intercept add up to its logit. No
|
||||
/// contributions when the probability is not the logistic's (the MLP champion, or nothing seen).
|
||||
/// </summary>
|
||||
public sealed record ScoreExplanation(double P, double Intercept, IReadOnlyList<FeatureValue> Features)
|
||||
{
|
||||
/// <summary>Nothing to explain: no probability, no contributions.</summary>
|
||||
public static readonly ScoreExplanation None = new(double.NaN, double.NaN, []);
|
||||
|
||||
/// <summary>Whether the contributions and the intercept give back <paramref name="p"/> (to <paramref name="tolerance"/>): a stored or a recomputed explanation may be shown next to it.</summary>
|
||||
public bool Explains(double p, double tolerance = 1e-6) =>
|
||||
Features.Count > 0 && double.IsFinite(p) && double.IsFinite(Intercept) &&
|
||||
Math.Abs(OnlineLogistic.Sigmoid(Features.Sum(static f => f.Contribution) + Intercept) - p) <= tolerance;
|
||||
}
|
||||
|
||||
/// <summary>One arm of the bandit: a preset in a volatility context.</summary>
|
||||
public sealed record BanditArm(
|
||||
int Context,
|
||||
string ContextLabel,
|
||||
string Preset,
|
||||
double Alpha,
|
||||
double Beta,
|
||||
int Successes,
|
||||
int Failures,
|
||||
int N,
|
||||
double Mean,
|
||||
double Low95,
|
||||
double High95,
|
||||
bool BestInContext);
|
||||
|
||||
/// <summary>The bandit's last proposal (never applied, D-30).</summary>
|
||||
public sealed record BanditProposal(DateTime Utc, int Context, string Preset, bool Explored, IReadOnlyList<double> Means, string Text);
|
||||
|
||||
/// <summary>The preset bandit (level 3).</summary>
|
||||
public sealed record BanditSummary(
|
||||
int Contexts,
|
||||
double ExplorationCap,
|
||||
int Choices,
|
||||
int Explorations,
|
||||
double ExplorationShare,
|
||||
string CurrentPreset,
|
||||
bool Applied,
|
||||
bool RewardsSuspect,
|
||||
IReadOnlyList<BanditArm> Arms,
|
||||
BanditProposal? LastProposal);
|
||||
|
||||
/// <summary>The σ forecasts at the closes the bandit's context is measured against.</summary>
|
||||
public sealed record VolatilityContextSummary(int HistoryCount, double TercileLow, double TercileHigh);
|
||||
|
||||
/// <summary>One row of <c>knowledge/calibration.csv</c> (level 0).</summary>
|
||||
public sealed record CalibrationTableRow(string Dimension, string Bucket, int Count, double WinRate, double MeanPnl, double TotalPnl, string Motivazione);
|
||||
|
||||
/// <summary>One row of <c>knowledge/proposals.csv</c>.</summary>
|
||||
public sealed record ProposalRow(DateTime? Utc, string Origin, string Parameter, string CurrentValue, string ProposedValue, string Evidence, string State, string Motivazione, bool BasedOnSuspectData);
|
||||
|
||||
/// <summary>One row of <c>knowledge/models_registry.csv</c>.</summary>
|
||||
public sealed record RegistryRow(string Version, DateTime? Utc, string Type, int NTrain, double AucWf, double Brier, double LogLoss, string State, string Motivazione);
|
||||
|
||||
/// <summary>The newest <c>knowledge/insights_*.md</c>, capped at 64 KB.</summary>
|
||||
public sealed record InsightsDoc(string FileName, DateTime ModifiedUtc, string Markdown, bool Truncated);
|
||||
|
||||
/// <summary>One model file of <c>data/models</c>.</summary>
|
||||
public sealed record ModelFileRow(string Name, long Bytes, DateTime ModifiedUtc, string Kind, int? Version, int? Rows);
|
||||
|
||||
/// <summary>One file of <c>knowledge/</c>.</summary>
|
||||
public sealed record FileRow(string Name, long Bytes, DateTime ModifiedUtc);
|
||||
|
||||
/// <summary>The forward test's net P&L from <c>knowledge/forward_registry.csv</c> (the operator writes it).</summary>
|
||||
public sealed record ForwardSummary(int Rows, double PnlNetUsd);
|
||||
|
||||
/// <summary>The knowledge base and the model files, as the disk has them.</summary>
|
||||
public sealed record KnowledgeSnapshot(
|
||||
IReadOnlyList<CalibrationTableRow> Calibration,
|
||||
IReadOnlyList<ProposalRow> Proposals,
|
||||
IReadOnlyList<RegistryRow> Registry,
|
||||
InsightsDoc? Insights,
|
||||
IReadOnlyList<ModelFileRow> ModelFiles,
|
||||
IReadOnlyList<FileRow> Files)
|
||||
{
|
||||
public static readonly KnowledgeSnapshot Empty = new([], [], [], null, [], []);
|
||||
|
||||
/// <summary>The forward test, when <c>forward_registry.csv</c> has rows (not part of the JSON: it feeds the activation checklist).</summary>
|
||||
public ForwardSummary? Forward { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>When the cycle ran, runs next, and what it is doing now.</summary>
|
||||
public sealed record CycleSchedule(
|
||||
DateTime? LastCycleUtc,
|
||||
DateTime? NextDueUtc,
|
||||
bool RunsInBot,
|
||||
bool Due,
|
||||
bool Running,
|
||||
DateTime? RunningSinceUtc,
|
||||
string RunningPhase,
|
||||
long? LastDurationMs,
|
||||
string LastError,
|
||||
string LastTrigger);
|
||||
|
||||
/// <summary>What a background cycle is doing (the runner's thread-safe picture).</summary>
|
||||
public sealed record CycleRunStatus(bool Running, DateTime? RunningSinceUtc, string Phase, string Trigger, string LastError, long? LastDurationMs, string LastTrigger, DateTime? LastFinishedUtc)
|
||||
{
|
||||
public static readonly CycleRunStatus Idle = new(false, null, string.Empty, string.Empty, string.Empty, null, string.Empty, null);
|
||||
}
|
||||
@@ -28,6 +28,30 @@ public sealed record ModelReport(
|
||||
$"{Model}: {Rows} basket, AUC {Auc:F3} [{AucLow:F3}; {AucHigh:F3}], Brier {Brier:F3}, log-loss {LogLoss:F3}; P&L tutti {PnlAll:F0} USD, filtrati ({FilteredCount}) {PnlFiltered:F0} USD, DSR {DsrFiltered:F2} → {(PassesActivation ? "ATTIVABILE" : "resta in ombra")}");
|
||||
}
|
||||
|
||||
/// <summary>The walk-forward of the logistic with what it computed: the rows in open order and the probability each got before it opened.</summary>
|
||||
public sealed record LogisticWalkForward(ModelReport Report, OnlineLogistic Model, IReadOnlyList<LabelledBasket> Ordered, IReadOnlyList<double> P)
|
||||
{
|
||||
/// <summary>
|
||||
/// The (p at entry, label) pairs after the burn-in, in close order: what the rolling AUC
|
||||
/// of the live model starts from after a cycle — the same probabilities, given before each
|
||||
/// basket opened, that the walk-forward AUC is computed on.
|
||||
/// </summary>
|
||||
public IReadOnlyList<(double P, int Label, DateTime ClosedUtc, string BasketId)> EntryPairs(int burnIn = ModelEvaluator.BurnIn)
|
||||
{
|
||||
List<(double P, int Label, DateTime ClosedUtc, string BasketId)> pairs = [];
|
||||
for (int i = Math.Max(0, burnIn); i < Ordered.Count && i < P.Count; i++)
|
||||
{
|
||||
if (double.IsFinite(P[i]))
|
||||
{
|
||||
pairs.Add((P[i], Ordered[i].Label, Ordered[i].ClosedUtc, Ordered[i].BasketId));
|
||||
}
|
||||
}
|
||||
|
||||
pairs.Sort(static (a, b) => a.ClosedUtc.CompareTo(b.ClosedUtc));
|
||||
return pairs;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Walk-forward evaluation of the meta-labelers on the ledger's labelled baskets.
|
||||
/// Level 1 is online, so its walk-forward is exact by construction: each prediction
|
||||
@@ -44,6 +68,18 @@ public static class ModelEvaluator
|
||||
|
||||
/// <summary>Level 1: sequential predict-then-update over the baskets, ordered by open time; the update happens only when the basket has closed.</summary>
|
||||
public static (ModelReport Report, OnlineLogistic Model) EvaluateLogistic(IReadOnlyList<LabelledBasket> rows, double pMin, int seed = 42)
|
||||
{
|
||||
LogisticWalkForward wf = EvaluateLogisticWalkForward(rows, pMin, CancellationToken.None, seed);
|
||||
return (wf.Report, wf.Model);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// <see cref="EvaluateLogistic"/> keeping what it computed on the way: the rows in open
|
||||
/// order and, for each, the probability the model gave <b>before</b> the basket opened (only
|
||||
/// baskets closed by then taught it). The rolling performance of the live model starts from
|
||||
/// these after a cycle. <paramref name="ct"/> is checked every 64 rows.
|
||||
/// </summary>
|
||||
public static LogisticWalkForward EvaluateLogisticWalkForward(IReadOnlyList<LabelledBasket> rows, double pMin, CancellationToken ct, int seed = 42)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
List<LabelledBasket> ordered = [.. rows.OrderBy(static r => r.OpenedUtc)];
|
||||
@@ -55,6 +91,11 @@ public static class ModelEvaluator
|
||||
List<(DateTime ClosedUtc, int Index)> pending = [];
|
||||
for (int i = 0; i < ordered.Count; i++)
|
||||
{
|
||||
if ((i & 63) == 0)
|
||||
{
|
||||
ct.ThrowIfCancellationRequested();
|
||||
}
|
||||
|
||||
DateTime open = ordered[i].OpenedUtc;
|
||||
foreach ((DateTime closed, int idx) in pending.Where(x => x.ClosedUtc <= open).OrderBy(static x => x.ClosedUtc).ToList())
|
||||
{
|
||||
@@ -71,11 +112,12 @@ public static class ModelEvaluator
|
||||
model.Update(ordered[idx].Features, ordered[idx].Label);
|
||||
}
|
||||
|
||||
return (Report("logistica", ordered, p, pMin, seed), model);
|
||||
ct.ThrowIfCancellationRequested();
|
||||
return new LogisticWalkForward(Report("logistica", ordered, p, pMin, seed), model, ordered, p);
|
||||
}
|
||||
|
||||
/// <summary>Level 2: five chronological folds, purge/embargo of 24 h, early stopping on the tail of the training rows, five seeds averaged.</summary>
|
||||
public static (ModelReport Report, SmallMlp? Model) EvaluateMlp(IReadOnlyList<LabelledBasket> rows, double pMin, int folds = 5, int[]? seeds = null)
|
||||
/// <summary>Level 2: five chronological folds, purge/embargo of 24 h, early stopping on the tail of the training rows, five seeds averaged. <paramref name="ct"/> is checked between folds, seeds and epochs.</summary>
|
||||
public static (ModelReport Report, SmallMlp? Model) EvaluateMlp(IReadOnlyList<LabelledBasket> rows, double pMin, int folds = 5, int[]? seeds = null, CancellationToken ct = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(rows);
|
||||
seeds ??= [42, 43, 44, 45, 46];
|
||||
@@ -91,6 +133,7 @@ public static class ModelEvaluator
|
||||
TimeSpan embargo = TimeSpan.FromHours(24);
|
||||
for (int k = 0; k < folds; k++)
|
||||
{
|
||||
ct.ThrowIfCancellationRequested();
|
||||
int from = k * n / folds;
|
||||
int to = (k + 1) * n / folds;
|
||||
DateTime testStart = ordered[from].OpenedUtc;
|
||||
@@ -120,7 +163,8 @@ public static class ModelEvaluator
|
||||
double[][] preds = new double[seeds.Length][];
|
||||
for (int s = 0; s < seeds.Length; s++)
|
||||
{
|
||||
SmallMlp m = Train(ordered, train, seeds[s]);
|
||||
ct.ThrowIfCancellationRequested();
|
||||
SmallMlp m = Train(ordered, train, seeds[s], ct: ct);
|
||||
preds[s] = new double[to - from];
|
||||
for (int i = from; i < to; i++)
|
||||
{
|
||||
@@ -152,12 +196,13 @@ public static class ModelEvaluator
|
||||
}
|
||||
}
|
||||
|
||||
SmallMlp final = Train(ordered, [.. Enumerable.Range(0, n)], seeds[0]);
|
||||
ct.ThrowIfCancellationRequested();
|
||||
SmallMlp final = Train(ordered, [.. Enumerable.Range(0, n)], seeds[0], ct: ct);
|
||||
return (Report("mlp16", evaluated, [.. scores], pMin, seeds[0], burnIn: 0), final);
|
||||
}
|
||||
|
||||
/// <summary>Mini-batch Adam with early stopping on the last 20 % of the training rows (chronological, purged by 24 h).</summary>
|
||||
public static SmallMlp Train(IReadOnlyList<LabelledBasket> ordered, IReadOnlyList<int> train, int seed, int maxEpochs = 300, int patience = 20)
|
||||
/// <summary>Mini-batch Adam with early stopping on the last 20 % of the training rows (chronological, purged by 24 h). <paramref name="ct"/> is checked at every epoch.</summary>
|
||||
public static SmallMlp Train(IReadOnlyList<LabelledBasket> ordered, IReadOnlyList<int> train, int seed, int maxEpochs = 300, int patience = 20, CancellationToken ct = default)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(ordered);
|
||||
ArgumentNullException.ThrowIfNull(train);
|
||||
@@ -193,6 +238,7 @@ public static class ModelEvaluator
|
||||
|
||||
for (int epoch = 0; epoch < maxEpochs; epoch++)
|
||||
{
|
||||
ct.ThrowIfCancellationRequested();
|
||||
rng.Shuffle(order);
|
||||
for (int start = 0; start < order.Length; start += batch)
|
||||
{
|
||||
|
||||
@@ -39,8 +39,32 @@ public sealed class RollingStandardizer
|
||||
_alpha = 1 - Math.Pow(0.5, 1.0 / Math.Max(1, halfLifeRows));
|
||||
}
|
||||
|
||||
private RollingStandardizer(int size, double alpha, bool fromAlpha)
|
||||
{
|
||||
_mean = new double[size];
|
||||
_var = new double[size];
|
||||
_alpha = fromAlpha && alpha is > 0 and < 1 ? alpha : 1 - Math.Pow(0.5, 1.0 / 200);
|
||||
}
|
||||
|
||||
public long Count => _n;
|
||||
|
||||
/// <summary>The rows after which an old row weighs half: <c>ln ½ / ln(1 − α)</c>.</summary>
|
||||
public double HalfLifeRows => _alpha is > 0 and < 1 ? Math.Log(0.5) / Math.Log(1 - _alpha) : double.NaN;
|
||||
|
||||
/// <summary>What the standardiser knows now, copied (a reader never sees it move): rows, half-life, mean and standard deviation per feature (NaN before the first row).</summary>
|
||||
public StandardizerStats Stats()
|
||||
{
|
||||
double[] mean = new double[_mean.Length];
|
||||
double[] sd = new double[_mean.Length];
|
||||
for (int i = 0; i < _mean.Length; i++)
|
||||
{
|
||||
mean[i] = _n > 0 ? _mean[i] : double.NaN;
|
||||
sd[i] = _n > 0 ? Math.Sqrt(Math.Max(0, _var[i])) : double.NaN;
|
||||
}
|
||||
|
||||
return new StandardizerStats(_n, HalfLifeRows, mean, sd);
|
||||
}
|
||||
|
||||
/// <summary>Standardises a row with the statistics seen so far, then updates them. NaN inputs become 0 (the mean).</summary>
|
||||
public double[] Transform(double[] x, bool update)
|
||||
{
|
||||
@@ -134,7 +158,8 @@ public sealed class RollingStandardizer
|
||||
public static RollingStandardizer Read(JsonElement e)
|
||||
{
|
||||
double[] mean = Nums(e.GetProperty("mean"));
|
||||
RollingStandardizer s = new(mean.Length);
|
||||
double alpha = e.TryGetProperty("alpha", out JsonElement a) && a.ValueKind == JsonValueKind.Number ? a.GetDouble() : double.NaN;
|
||||
RollingStandardizer s = new(mean.Length, alpha, fromAlpha: true);
|
||||
Array.Copy(mean, s._mean, mean.Length);
|
||||
Array.Copy(Nums(e.GetProperty("var")), s._var, mean.Length);
|
||||
s._n = e.GetProperty("n").GetInt64();
|
||||
@@ -155,6 +180,9 @@ public sealed class RollingStandardizer
|
||||
internal static double[] Nums(JsonElement e) => [.. e.EnumerateArray().Select(static x => x.GetDouble())];
|
||||
}
|
||||
|
||||
/// <summary>A copy of a <see cref="RollingStandardizer"/>'s statistics.</summary>
|
||||
public sealed record StandardizerStats(long Count, double HalfLifeRows, IReadOnlyList<double> Mean, IReadOnlyList<double> StdDev);
|
||||
|
||||
/// <summary>
|
||||
/// Level 1 of the learning stack (§8.3): logistic regression trained online by SGD with
|
||||
/// L2, on rolling-standardised features. Starts in shadow mode: it predicts, the engine
|
||||
@@ -183,8 +211,98 @@ public sealed class OnlineLogistic : IModel
|
||||
|
||||
public int Seen => _seen;
|
||||
|
||||
/// <summary>The initial learning rate <c>lr₀</c>.</summary>
|
||||
public double LearningRate0 => _lr0;
|
||||
|
||||
/// <summary>The L2 penalty.</summary>
|
||||
public double L2 => _l2;
|
||||
|
||||
/// <summary>The intercept.</summary>
|
||||
public double Bias => _b;
|
||||
|
||||
/// <summary>Learning rate with a slow decay: <c>lr₀ / (1 + n/1000)</c>.</summary>
|
||||
private double LearningRate => _lr0 / (1 + (_seen / 1000.0));
|
||||
public double LearningRate => _lr0 / (1 + (_seen / 1000.0));
|
||||
|
||||
/// <summary>
|
||||
/// The model in numbers, read without changing anything: hyper-parameters, the weights by
|
||||
/// decreasing |w| (they act on standardised features, so |w| ranks what matters) with the
|
||||
/// standardiser's mean and standard deviation of their feature.
|
||||
/// </summary>
|
||||
public LogisticSummary Summarize()
|
||||
{
|
||||
StandardizerStats s = _std.Stats();
|
||||
List<FeatureWeight> weights = new(_w.Length);
|
||||
double norm = 0;
|
||||
for (int i = 0; i < _w.Length; i++)
|
||||
{
|
||||
norm += _w[i] * _w[i];
|
||||
weights.Add(new FeatureWeight(i, NameOf(i), LabelOf(i), _w[i], i < s.Mean.Count ? s.Mean[i] : double.NaN, i < s.StdDev.Count ? s.StdDev[i] : double.NaN));
|
||||
}
|
||||
|
||||
weights.Sort(static (a, b) =>
|
||||
{
|
||||
int c = Math.Abs(b.Weight).CompareTo(Math.Abs(a.Weight));
|
||||
return c != 0 ? c : a.Index.CompareTo(b.Index);
|
||||
});
|
||||
return new LogisticSummary(_w.Length, _seen, _lr0, LearningRate, _l2, _b, Math.Sqrt(norm), s.Count, s.HalfLifeRows, weights);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// What pushes the prediction for one row, feature by feature in index order: the value,
|
||||
/// its standardised value (with the statistics seen so far, not updated) and its share of
|
||||
/// the logit, <c>w·z</c>. Pure.
|
||||
/// </summary>
|
||||
public IReadOnlyList<FeatureValue> Explain(double[] features)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(features);
|
||||
double[] z = _std.Transform(features, update: false);
|
||||
FeatureValue[] values = new FeatureValue[_w.Length];
|
||||
for (int i = 0; i < _w.Length; i++)
|
||||
{
|
||||
double value = i < features.Length ? features[i] : double.NaN;
|
||||
values[i] = new FeatureValue(i, NameOf(i), LabelOf(i), value, z[i], _w[i] * z[i]);
|
||||
}
|
||||
|
||||
return values;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The probability for one row with what made it, in one read of the weights (5.1 review):
|
||||
/// the contributions and the intercept add up to its logit. NaN and no contributions before
|
||||
/// the model has seen a basket, as the champion's prediction. Pure.
|
||||
/// </summary>
|
||||
public ScoreExplanation Score(double[] features)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(features);
|
||||
return _seen == 0 ? ScoreExplanation.None : new ScoreExplanation(Predict(features), _b, Explain(features));
|
||||
}
|
||||
|
||||
/// <summary>The values of <see cref="Explain"/> from a vector and the standardised values and contributions kept with it (an entry remembered with its explanation).</summary>
|
||||
public static IReadOnlyList<FeatureValue> Rebuild(IReadOnlyList<double> features, IReadOnlyList<double> z, IReadOnlyList<double> contributions)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(features);
|
||||
ArgumentNullException.ThrowIfNull(z);
|
||||
ArgumentNullException.ThrowIfNull(contributions);
|
||||
int n = Math.Min(features.Count, Math.Min(z.Count, contributions.Count));
|
||||
FeatureValue[] values = new FeatureValue[n];
|
||||
for (int i = 0; i < n; i++)
|
||||
{
|
||||
values[i] = new FeatureValue(i, NameOf(i), LabelOf(i), features[i], z[i], contributions[i]);
|
||||
}
|
||||
|
||||
return values;
|
||||
}
|
||||
|
||||
/// <summary>The largest contributions of <see cref="Explain"/> by |w·z|.</summary>
|
||||
public static IReadOnlyList<FeatureValue> Top(IReadOnlyList<FeatureValue> values, int count)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(values);
|
||||
return [.. values.Where(static v => double.IsFinite(v.Contribution)).OrderByDescending(static v => Math.Abs(v.Contribution)).ThenBy(static v => v.Index).Take(Math.Max(0, count))];
|
||||
}
|
||||
|
||||
private static string NameOf(int i) => i < LearningFeatures.Names.Length ? LearningFeatures.Names[i] : string.Create(CultureInfo.InvariantCulture, $"f{i}");
|
||||
|
||||
private static string LabelOf(int i) => i < LearningFeatures.Labels.Length ? LearningFeatures.Labels[i] : NameOf(i);
|
||||
|
||||
public double Predict(double[] features)
|
||||
{
|
||||
|
||||
@@ -224,6 +224,35 @@ public sealed class SmallMlp : IModel
|
||||
|
||||
public void MarkSeen(int rows) => _seen = rows;
|
||||
|
||||
/// <summary>The hidden units, the size of the network's middle layer.</summary>
|
||||
public int Hidden => _hidden;
|
||||
|
||||
/// <summary>
|
||||
/// The network in numbers, read without changing anything: the norms of the two layers,
|
||||
/// the output bias and the hidden units whose outgoing weight is below 10⁻³ (switched off:
|
||||
/// whatever they compute never reaches the output).
|
||||
/// </summary>
|
||||
public MlpSummary Summarize(bool challengerWins)
|
||||
{
|
||||
double w1 = 0, w2 = 0;
|
||||
foreach (double v in _w1)
|
||||
{
|
||||
w1 += v * v;
|
||||
}
|
||||
|
||||
int silent = 0;
|
||||
foreach (double v in _w2)
|
||||
{
|
||||
w2 += v * v;
|
||||
if (Math.Abs(v) < 1e-3)
|
||||
{
|
||||
silent++;
|
||||
}
|
||||
}
|
||||
|
||||
return new MlpSummary(_hidden, _seed, _seen, _b2, Math.Sqrt(w1), Math.Sqrt(w2), silent, _std.Count, challengerWins);
|
||||
}
|
||||
|
||||
public string ToJson()
|
||||
{
|
||||
using MemoryStream ms = new();
|
||||
|
||||
@@ -6,8 +6,9 @@ namespace Encelado.Core.Baskets.Learning;
|
||||
/// <summary>
|
||||
/// Level 3 (§8.6): Thompson sampling with Beta posteriors, one arm per (preset ×
|
||||
/// volatility tercile). Reward 1 when a basket closes with a net profit, 0 otherwise.
|
||||
/// It proposes; the engine applies the proposal only in paper/demo, and never in live
|
||||
/// until the forward test says so. Exploration is capped at 10 % of the choices.
|
||||
/// It proposes and never applies (since 5.0): the preset is the operator's choice in the
|
||||
/// settings, and a proposal goes through the forward test. Exploration is capped at 10 %
|
||||
/// of the choices.
|
||||
/// <para>
|
||||
/// Why a bandit and not deep RL: with a few hundred episodes a year, three arms per
|
||||
/// context and a binary reward are what the data can tell apart; a value network would
|
||||
@@ -44,6 +45,59 @@ public sealed class ThompsonBandit
|
||||
|
||||
public int Choices => _choices;
|
||||
|
||||
/// <summary>How many proposals were exploratory (sampled away from the best posterior mean).</summary>
|
||||
public int Explorations => _explorations;
|
||||
|
||||
/// <summary>The volatility contexts (terciles): 3.</summary>
|
||||
public int Contexts => _contexts;
|
||||
|
||||
/// <summary>The Italian label of a volatility context.</summary>
|
||||
public static string ContextLabel(int context) => context switch
|
||||
{
|
||||
0 => "vol bassa",
|
||||
1 => "vol media",
|
||||
2 => "vol alta",
|
||||
_ => "n/d",
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// Every arm's posterior, read without drawing anything: α and β, the rewards behind them
|
||||
/// (α − 1 wins, β − 1 losses on the Beta(1, 1) prior), the posterior mean with its 95 %
|
||||
/// credible interval, and whether it is the best mean of its context. An arm never tried
|
||||
/// is never the best (5.1 review): its mean is the prior's, not something learnt, so a
|
||||
/// fresh bandit has no best arm, and neither has a context whose tried arms do no better
|
||||
/// than the prior. In context order, arms in preset order (Conservative, Moderate, Aggressive).
|
||||
/// </summary>
|
||||
public IReadOnlyList<BanditArm> Arms()
|
||||
{
|
||||
List<BanditArm> arms = new(_contexts * 3);
|
||||
for (int c = 0; c < _contexts; c++)
|
||||
{
|
||||
double[] means = new double[3];
|
||||
for (int a = 0; a < 3; a++)
|
||||
{
|
||||
means[a] = _alpha[c, a] / (_alpha[c, a] + _beta[c, a]);
|
||||
}
|
||||
|
||||
int best = ArgMax(means);
|
||||
for (int a = 0; a < 3; a++)
|
||||
{
|
||||
double alpha = _alpha[c, a], beta = _beta[c, a];
|
||||
int wins = (int)Math.Round(Math.Max(0, alpha - 1));
|
||||
int losses = (int)Math.Round(Math.Max(0, beta - 1));
|
||||
int n = wins + losses;
|
||||
arms.Add(new BanditArm(c, ContextLabel(c), ((PresetName)a).ToString(), alpha, beta, wins, losses, n, means[a],
|
||||
Statistics.BetaDistribution.Quantile(0.025, alpha, beta), Statistics.BetaDistribution.Quantile(0.975, alpha, beta), a == best && n > 0));
|
||||
}
|
||||
}
|
||||
|
||||
return arms;
|
||||
}
|
||||
|
||||
/// <summary>The bandit for the report: counts, exploration share, arms, the last proposal. <c>applied</c> is always false (D-30).</summary>
|
||||
public BanditSummary Summarize(string currentPreset, BanditProposal? lastProposal, bool rewardsSuspect) =>
|
||||
new(_contexts, ExplorationCap, _choices, _explorations, _choices > 0 ? (double)_explorations / _choices : double.NaN, currentPreset, false, rewardsSuspect, Arms(), lastProposal);
|
||||
|
||||
/// <summary>Proposes a preset for the context. Greedy on the posterior mean, except for a capped share of sampled (exploratory) choices.</summary>
|
||||
public (PresetName Preset, bool Explored, double[] Means) Propose(int context)
|
||||
{
|
||||
|
||||
@@ -3,6 +3,42 @@ using Encelado.Core.Statistics;
|
||||
|
||||
namespace Encelado.Core.Baskets.Learning;
|
||||
|
||||
/// <summary>
|
||||
/// What a <see cref="VolForecaster"/> knows at one instant, read without side effects: no
|
||||
/// forecast is queued for scoring and the model in use is not changed (5.1, decision E1).
|
||||
/// σ values are per 15-minute bar, in return units; NaN when unknown.
|
||||
/// </summary>
|
||||
public sealed record VolStats(
|
||||
int Bars,
|
||||
string ActiveModel,
|
||||
double EwmaSigma,
|
||||
double HarSigma,
|
||||
double ForecastSigma,
|
||||
double Average30dSigma,
|
||||
double RmseEwma,
|
||||
double RmseHar,
|
||||
int Scored,
|
||||
int Pending,
|
||||
DateTime? LastHarFitUtc)
|
||||
{
|
||||
public static readonly VolStats Empty = new(0, "EWMA", double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, double.NaN, 0, 0, null);
|
||||
|
||||
/// <summary>Forecast over the 30-day average: the zIn scale before its clamp; NaN when either is unknown.</summary>
|
||||
public double Ratio => double.IsFinite(ForecastSigma) && double.IsFinite(Average30dSigma) && Average30dSigma > 0 ? ForecastSigma / Average30dSigma : double.NaN;
|
||||
|
||||
/// <summary>One line for the console and the 5.0 panel.</summary>
|
||||
public string Describe()
|
||||
{
|
||||
if (Scored == 0)
|
||||
{
|
||||
return string.Create(CultureInfo.InvariantCulture, $"EWMA σ {(double.IsFinite(EwmaSigma) ? EwmaSigma : 0):0.0000} per barra, HAR non ancora confrontabile ({Bars} barre)");
|
||||
}
|
||||
|
||||
return string.Create(CultureInfo.InvariantCulture,
|
||||
$"{ActiveModel} in uso; errore quadratico medio su {Scored} previsioni: EWMA {RmseEwma:0.00000}, HAR {RmseHar:0.00000}; σ prevista {ForecastSigma:0.0000} per barra");
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// "Forward thinking" for volatility (§8.5): the next 1-4 hours' realised volatility of
|
||||
/// the synthetic cross, by an EWMA baseline and by HAR-RV on 15-minute realised
|
||||
@@ -17,6 +53,7 @@ public sealed class VolForecaster
|
||||
private readonly List<(double Ewma, double Har, double Realised)> _scores = [];
|
||||
private double[]? _beta;
|
||||
private DateTime _lastFitUtc = DateTime.MinValue;
|
||||
private DateTime? _harFittedUtc;
|
||||
private double _ewmaVar;
|
||||
private bool _ewmaSeeded;
|
||||
|
||||
@@ -37,6 +74,7 @@ public sealed class VolForecaster
|
||||
{
|
||||
double r2 = logReturn * logReturn;
|
||||
_rv.Add(r2);
|
||||
_bars++;
|
||||
if (_rv.Count > 20_000)
|
||||
{
|
||||
_rv.RemoveAt(0);
|
||||
@@ -52,14 +90,16 @@ public sealed class VolForecaster
|
||||
_ewmaVar = ((1 - EwmaAlpha) * _ewmaVar) + (EwmaAlpha * r2);
|
||||
}
|
||||
|
||||
// Score the forecasts made `horizon` bars ago against what happened.
|
||||
if (_pending.Count > 0 && _rv.Count - _pending.Peek().At >= _horizonBars)
|
||||
// Score the forecasts made `horizon` bars ago against what happened. Bar numbers are
|
||||
// absolute (the history keeps the last 20 000 bars): _rv[0] is bar _bars − _rv.Count.
|
||||
if (_pending.Count > 0 && _bars - _pending.Peek().At >= _horizonBars)
|
||||
{
|
||||
(int at, double e, double h) = _pending.Dequeue();
|
||||
(long at, double e, double h) = _pending.Dequeue();
|
||||
long first = _bars - _rv.Count;
|
||||
double realised = 0;
|
||||
for (int i = at; i < Math.Min(_rv.Count, at + _horizonBars); i++)
|
||||
for (long i = Math.Max(at, first); i < Math.Min(_bars, at + _horizonBars); i++)
|
||||
{
|
||||
realised += _rv[i];
|
||||
realised += _rv[(int)(i - first)];
|
||||
}
|
||||
|
||||
realised = Math.Sqrt(realised / _horizonBars);
|
||||
@@ -72,14 +112,33 @@ public sealed class VolForecaster
|
||||
|
||||
if (nowUtc - _lastFitUtc >= TimeSpan.FromDays(1) && _rv.Count >= 96 * 5)
|
||||
{
|
||||
Fit();
|
||||
if (Fit())
|
||||
{
|
||||
_harFittedUtc = nowUtc;
|
||||
}
|
||||
|
||||
_lastFitUtc = nowUtc;
|
||||
}
|
||||
}
|
||||
|
||||
private readonly Queue<(int At, double Ewma, double Har)> _pending = new();
|
||||
private readonly Queue<(long At, double Ewma, double Har)> _pending = new();
|
||||
|
||||
/// <summary>Per-bar volatility forecast for the next horizon (in return units per bar).</summary>
|
||||
/// <summary>Bars observed since the start (absolute, unlike <see cref="Count"/> which stops at the history's cap).</summary>
|
||||
private long _bars;
|
||||
|
||||
/// <summary>The bar (absolute) whose forecast is already queued for scoring; −1 before the first.</summary>
|
||||
private long _queuedAt = -1;
|
||||
|
||||
/// <summary>Forecasts waiting for their horizon to be scored: one per bar at most, so never more than the horizon and a few.</summary>
|
||||
public int PendingCount => _pending.Count;
|
||||
|
||||
/// <summary>
|
||||
/// Per-bar volatility forecast for the next horizon (in return units per bar). The engine
|
||||
/// asks at every bar close and, for an open basket, at every poll: only the first forecast
|
||||
/// of a bar is queued for scoring (5.1) — the score compares one forecast per bar with
|
||||
/// what the next <c>horizon</c> bars realised, never a forecast made hours before, and the
|
||||
/// queue stays bounded.
|
||||
/// </summary>
|
||||
public double Forecast()
|
||||
{
|
||||
if (!_ewmaSeeded)
|
||||
@@ -89,7 +148,17 @@ public sealed class VolForecaster
|
||||
|
||||
double ewma = Math.Sqrt(_ewmaVar);
|
||||
double har = HarForecast();
|
||||
_pending.Enqueue((_rv.Count, ewma, double.IsFinite(har) ? har : ewma));
|
||||
if (_queuedAt != _bars)
|
||||
{
|
||||
_queuedAt = _bars;
|
||||
_pending.Enqueue((_bars, ewma, double.IsFinite(har) ? har : ewma));
|
||||
|
||||
// A safety net: nothing above can let it grow, but a long gap without Observe must not either.
|
||||
while (_pending.Count > (4 * _horizonBars) + 4)
|
||||
{
|
||||
_pending.Dequeue();
|
||||
}
|
||||
}
|
||||
|
||||
ActiveModel = ChooseModel();
|
||||
return ActiveModel == "HAR" && double.IsFinite(har) ? har : ewma;
|
||||
@@ -102,6 +171,12 @@ public sealed class VolForecaster
|
||||
return "EWMA";
|
||||
}
|
||||
|
||||
(double e, double h) = SquaredErrors();
|
||||
return h < e ? "HAR" : "EWMA";
|
||||
}
|
||||
|
||||
private (double Ewma, double Har) SquaredErrors()
|
||||
{
|
||||
double e = 0, h = 0;
|
||||
foreach ((double ewma, double har, double realised) in _scores)
|
||||
{
|
||||
@@ -109,7 +184,7 @@ public sealed class VolForecaster
|
||||
h += (har - realised) * (har - realised);
|
||||
}
|
||||
|
||||
return h < e ? "HAR" : "EWMA";
|
||||
return (e, h);
|
||||
}
|
||||
|
||||
private double HarForecast()
|
||||
@@ -146,13 +221,13 @@ public sealed class VolForecaster
|
||||
return n > 0 ? s / n : 0;
|
||||
}
|
||||
|
||||
/// <summary>OLS of the next-bar RV on the daily/weekly/monthly components (here 15 min / 4 h / 24 h).</summary>
|
||||
private void Fit()
|
||||
/// <summary>OLS of the next-bar RV on the daily/weekly/monthly components (here 15 min / 4 h / 24 h). True when a fit was made.</summary>
|
||||
private bool Fit()
|
||||
{
|
||||
int n = Math.Min(_rv.Count - 97, 96 * 60);
|
||||
if (n < 200)
|
||||
{
|
||||
return;
|
||||
return false;
|
||||
}
|
||||
|
||||
List<double[]> x = new(n);
|
||||
@@ -166,10 +241,13 @@ public sealed class VolForecaster
|
||||
}
|
||||
|
||||
OlsFit? fit = Ols.Fit(x, y);
|
||||
if (fit is not null)
|
||||
if (fit is null)
|
||||
{
|
||||
_beta = fit.Coefficients;
|
||||
return false;
|
||||
}
|
||||
|
||||
_beta = fit.Coefficients;
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>Average forecast over the last <paramref name="days"/> days of bars (for the zIn scaling of §5.8).</summary>
|
||||
@@ -190,22 +268,29 @@ public sealed class VolForecaster
|
||||
return Math.Sqrt(s / n);
|
||||
}
|
||||
|
||||
public string Describe()
|
||||
/// <summary>
|
||||
/// Everything the forecaster knows, without side effects: nothing is queued for scoring
|
||||
/// and <see cref="ActiveModel"/> does not change (a panel refreshed every second must not
|
||||
/// bias the EWMA/HAR choice). Called on the thread that feeds <see cref="Observe"/>.
|
||||
/// </summary>
|
||||
public VolStats Stats(int averageDays = 30)
|
||||
{
|
||||
if (_scores.Count == 0)
|
||||
double ewma = _ewmaSeeded ? Math.Sqrt(_ewmaVar) : double.NaN;
|
||||
double har = HarForecast();
|
||||
string model = ChooseModel();
|
||||
double forecast = !_ewmaSeeded ? double.NaN : model == "HAR" && double.IsFinite(har) ? har : ewma;
|
||||
double rmseEwma = double.NaN, rmseHar = double.NaN;
|
||||
if (_scores.Count > 0)
|
||||
{
|
||||
return string.Create(CultureInfo.InvariantCulture, $"EWMA σ {Math.Sqrt(_ewmaVar):0.0000} per barra, HAR non ancora confrontabile ({_rv.Count} barre)");
|
||||
(double e, double h) = SquaredErrors();
|
||||
rmseEwma = Math.Sqrt(e / _scores.Count);
|
||||
rmseHar = Math.Sqrt(h / _scores.Count);
|
||||
}
|
||||
|
||||
double e = 0, h = 0;
|
||||
foreach ((double ewma, double har, double realised) in _scores)
|
||||
{
|
||||
e += (ewma - realised) * (ewma - realised);
|
||||
h += (har - realised) * (har - realised);
|
||||
}
|
||||
|
||||
return string.Create(CultureInfo.InvariantCulture,
|
||||
$"{ActiveModel} in uso; errore quadratico medio su {_scores.Count} previsioni: EWMA {Math.Sqrt(e / _scores.Count):0.00000}, HAR {Math.Sqrt(h / _scores.Count):0.00000}; σ prevista {Forecast():0.0000} per barra");
|
||||
return new VolStats(_rv.Count, model, ewma, har, forecast, AverageVolatility(averageDays), rmseEwma, rmseHar, _scores.Count, _pending.Count, _harFittedUtc);
|
||||
}
|
||||
|
||||
/// <summary>One line for the console and the old panel; pure, like <see cref="Stats"/>.</summary>
|
||||
public string Describe() => Stats().Describe();
|
||||
}
|
||||
|
||||
@@ -156,6 +156,13 @@ public sealed class TrackedOrder
|
||||
/// matches it appears on the account. The register is persisted to
|
||||
/// <c>data/state/pending_orders.json</c> with atomic writes and reloaded at startup, so
|
||||
/// nothing sent is ever forgotten across a restart.
|
||||
/// <para>
|
||||
/// One file for both accounts, every order marked with the mode that sent it (5.1 review):
|
||||
/// a register opened for an account sees, resolves, fails and prunes only that account's
|
||||
/// orders; the other account's stay in the file untouched until an engine of that account
|
||||
/// runs again. An order without a mode (written before modes were recorded) belongs to
|
||||
/// whichever account opens the register, as it always did.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public sealed class OrderTracker
|
||||
{
|
||||
@@ -166,12 +173,16 @@ public sealed class OrderTracker
|
||||
public static readonly TimeSpan Retention = TimeSpan.FromHours(48);
|
||||
|
||||
private readonly string _path;
|
||||
private readonly ExecutionMode? _account;
|
||||
private readonly Lock _gate = new();
|
||||
private readonly Dictionary<string, TrackedOrder> _orders = new(StringComparer.Ordinal);
|
||||
|
||||
public OrderTracker(string path)
|
||||
/// <param name="path">The register's file; empty for one kept in memory only.</param>
|
||||
/// <param name="account">The account whose orders this register works on (its mode); null for every order in the file.</param>
|
||||
public OrderTracker(string path, ExecutionMode? account = null)
|
||||
{
|
||||
_path = path ?? string.Empty;
|
||||
_account = account;
|
||||
Load();
|
||||
}
|
||||
|
||||
@@ -180,13 +191,22 @@ public sealed class OrderTracker
|
||||
|
||||
public string Path => _path;
|
||||
|
||||
/// <summary>
|
||||
/// Whether an order sent in <paramref name="orderMode"/> belongs to <paramref name="account"/>:
|
||||
/// the same account (Demo or Live, whatever name a version gave the mode), or no mode recorded.
|
||||
/// </summary>
|
||||
public static bool BelongsTo(string? orderMode, ExecutionMode? account) =>
|
||||
account is not { } a || !ExecutionModeExtensions.TryParse(orderMode, out ExecutionMode m) || m.IsLive() == a.IsLive();
|
||||
|
||||
private bool Owns(TrackedOrder o) => BelongsTo(o.Mode, _account);
|
||||
|
||||
public IReadOnlyList<TrackedOrder> Pending
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return [.. _orders.Values.Where(static o => o.IsPending).OrderBy(static o => o.SentUtc)];
|
||||
return [.. _orders.Values.Where(o => o.IsPending && Owns(o)).OrderBy(static o => o.SentUtc)];
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -197,7 +217,7 @@ public sealed class OrderTracker
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return [.. _orders.Values.OrderBy(static o => o.SentUtc)];
|
||||
return [.. _orders.Values.Where(Owns).OrderBy(static o => o.SentUtc)];
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -208,7 +228,19 @@ public sealed class OrderTracker
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return _orders.Values.Count(static o => o.IsPending);
|
||||
return _orders.Values.Count(o => o.IsPending && Owns(o));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Orders of the other account still without an outcome: kept in the file, never touched here.</summary>
|
||||
public int OtherAccountPendingCount
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return _orders.Values.Count(o => o.IsPending && !Owns(o));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -250,7 +282,7 @@ public sealed class OrderTracker
|
||||
Dictionary<long, string> map = [];
|
||||
foreach (TrackedOrder o in _orders.Values)
|
||||
{
|
||||
if (o.Resolution == OrderResolution.Filled && o.PositionId > 0 && o.Leg is not (OrderLeg.Close or OrderLeg.Unwind))
|
||||
if (Owns(o) && o.Resolution == OrderResolution.Filled && o.PositionId > 0 && o.Leg is not (OrderLeg.Close or OrderLeg.Unwind))
|
||||
{
|
||||
map[o.PositionId] = o.Basket;
|
||||
}
|
||||
@@ -260,12 +292,12 @@ public sealed class OrderTracker
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Drops resolved orders older than <see cref="Retention"/>. Pending ones are never dropped.</summary>
|
||||
/// <summary>Drops resolved orders older than <see cref="Retention"/>. Pending ones are never dropped, nor the other account's.</summary>
|
||||
public int Prune(DateTime now)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
List<string> gone = [.. _orders.Values.Where(o => !o.IsPending && o.ResolvedUtc is { } r && now - r > Retention).Select(static o => o.ClientRef)];
|
||||
List<string> gone = [.. _orders.Values.Where(o => Owns(o) && !o.IsPending && o.ResolvedUtc is { } r && now - r > Retention).Select(static o => o.ClientRef)];
|
||||
foreach (string key in gone)
|
||||
{
|
||||
_orders.Remove(key);
|
||||
@@ -294,7 +326,7 @@ public sealed class OrderTracker
|
||||
HashSet<long> claimed;
|
||||
lock (_gate)
|
||||
{
|
||||
claimed = [.. _orders.Values.Where(static o => o.PositionId > 0).Select(static o => o.PositionId)];
|
||||
claimed = [.. _orders.Values.Where(o => o.PositionId > 0 && Owns(o)).Select(static o => o.PositionId)];
|
||||
}
|
||||
|
||||
foreach (TrackedOrder order in Pending)
|
||||
|
||||
@@ -25,6 +25,15 @@ public sealed class PendingEntry
|
||||
|
||||
public required double MaxLossUsd { get; init; }
|
||||
|
||||
/// <summary>The z stop of the preset at decision time (NaN in a plan saved before 5.1).</summary>
|
||||
public double ZStop { get; init; } = double.NaN;
|
||||
|
||||
/// <summary>The adds allowed by the preset at decision time (−1 in a plan saved before 5.1).</summary>
|
||||
public int MaxAdds { get; init; } = -1;
|
||||
|
||||
/// <summary>The label of the preset at decision time (empty in a plan saved before): the basket's own once it opens.</summary>
|
||||
public string Preset { get; init; } = string.Empty;
|
||||
|
||||
public double EntryCostPips { get; init; } = double.NaN;
|
||||
|
||||
public required double EquityAtEntry { get; init; }
|
||||
@@ -56,6 +65,13 @@ public sealed class PendingEntry
|
||||
w.WriteNumber("unitsB", UnitsB);
|
||||
w.WriteNumber("tpPips", TpPips);
|
||||
w.WriteNumber("maxLossUsd", MaxLossUsd);
|
||||
if (double.IsFinite(ZStop))
|
||||
{
|
||||
w.WriteNumber("zStop", ZStop);
|
||||
}
|
||||
|
||||
w.WriteNumber("maxAdds", MaxAdds);
|
||||
w.WriteString("preset", Preset);
|
||||
w.WriteNumber("entryCostPips", double.IsFinite(EntryCostPips) ? EntryCostPips : 0);
|
||||
w.WriteNumber("equityAtEntry", EquityAtEntry);
|
||||
w.WriteString("motivazione", Motivazione);
|
||||
@@ -83,6 +99,9 @@ public sealed class PendingEntry
|
||||
UnitsB = e.GetProperty("unitsB").GetDouble(),
|
||||
TpPips = e.GetProperty("tpPips").GetDouble(),
|
||||
MaxLossUsd = e.GetProperty("maxLossUsd").GetDouble(),
|
||||
ZStop = e.TryGetProperty("zStop", out JsonElement zs) && zs.ValueKind == JsonValueKind.Number ? zs.GetDouble() : double.NaN,
|
||||
MaxAdds = e.TryGetProperty("maxAdds", out JsonElement ma) && ma.ValueKind == JsonValueKind.Number ? ma.GetInt32() : -1,
|
||||
Preset = e.TryGetProperty("preset", out JsonElement pr) && pr.ValueKind == JsonValueKind.String ? pr.GetString() ?? string.Empty : string.Empty,
|
||||
EntryCostPips = e.GetProperty("entryCostPips").GetDouble(),
|
||||
EquityAtEntry = e.GetProperty("equityAtEntry").GetDouble(),
|
||||
Motivazione = e.GetProperty("motivazione").GetString() ?? string.Empty,
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
using Encelado.Core.Broker;
|
||||
|
||||
namespace Encelado.Core.Baskets;
|
||||
|
||||
/// <summary>
|
||||
/// What the venue's history says, at startup, about the balance saved before the stop:
|
||||
/// <paramref name="ClosedNet"/> is the realised net result (<c>netProfit − fees</c>) of every
|
||||
/// close after the saved reading, and <paramref name="Missing"/> the positions known to have
|
||||
/// closed since then that the history does not show yet.
|
||||
/// </summary>
|
||||
public sealed record StartupCashVerdict(double ClosedNet, IReadOnlyList<long> Missing)
|
||||
{
|
||||
/// <summary>Every known close is in the history: the balance can be judged now.</summary>
|
||||
public bool Complete => Missing.Count == 0;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The cash-movement check at startup (5.1 review): the saved balance against the account's,
|
||||
/// explained by the closes made since. The history lags a close by seconds to minutes, so a
|
||||
/// loss realised just before a restart would read as a withdrawal (a profit as a deposit)
|
||||
/// if the balance were judged while it does not show it. The verdict is given only when
|
||||
/// every position known to have closed since the saved reading — gone from the account
|
||||
/// since the last reconciliation, vanished and still unexplained before the stop, or closed
|
||||
/// by the bot and waiting for its settlement — appears in the history; otherwise the saved
|
||||
/// balance stays the reference and a later reconciliation judges, as it does in session.
|
||||
/// </summary>
|
||||
public static class StartupCash
|
||||
{
|
||||
/// <summary>
|
||||
/// The positions whose close the balance must already reflect: those on the account at
|
||||
/// the last reconciliation and gone now, those that vanished before the stop without a
|
||||
/// verdict, and those of the closes waiting for their settlement closed after the saved
|
||||
/// reading (earlier ones were judged with that reading).
|
||||
/// </summary>
|
||||
public static IReadOnlyList<long> Expected(
|
||||
IEnumerable<long> lastPositionIds,
|
||||
IReadOnlySet<long> onAccount,
|
||||
IEnumerable<long> vanishedUnsettled,
|
||||
IEnumerable<(IReadOnlyCollection<long> Ids, DateTime ClosedUtc)> pendingSettlements,
|
||||
DateTime lastObservedUtc)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(lastPositionIds);
|
||||
ArgumentNullException.ThrowIfNull(onAccount);
|
||||
ArgumentNullException.ThrowIfNull(vanishedUnsettled);
|
||||
ArgumentNullException.ThrowIfNull(pendingSettlements);
|
||||
HashSet<long> ids = [.. lastPositionIds.Where(id => !onAccount.Contains(id))];
|
||||
ids.UnionWith(vanishedUnsettled);
|
||||
foreach ((IReadOnlyCollection<long> settlementIds, DateTime closedUtc) in pendingSettlements)
|
||||
{
|
||||
if (closedUtc > lastObservedUtc)
|
||||
{
|
||||
ids.UnionWith(settlementIds.Where(id => !onAccount.Contains(id)));
|
||||
}
|
||||
}
|
||||
|
||||
ids.Remove(0);
|
||||
return [.. ids.Order()];
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The closes after <paramref name="lastObservedUtc"/> summed from the history (as the
|
||||
/// startup always summed them: every close changes the balance), and which of
|
||||
/// <paramref name="expected"/> the history does not show.
|
||||
/// </summary>
|
||||
public static StartupCashVerdict Judge(DateTime lastObservedUtc, IEnumerable<long> expected, IReadOnlyList<ClosedTrade> history)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(expected);
|
||||
ArgumentNullException.ThrowIfNull(history);
|
||||
HashSet<long> seen = [];
|
||||
double net = 0;
|
||||
foreach (ClosedTrade t in history)
|
||||
{
|
||||
seen.Add(t.PositionId);
|
||||
if (t.ClosedUtc > lastObservedUtc)
|
||||
{
|
||||
net += t.NetUsd;
|
||||
}
|
||||
}
|
||||
|
||||
return new StartupCashVerdict(net, [.. expected.Distinct().Where(id => !seen.Contains(id))]);
|
||||
}
|
||||
}
|
||||
@@ -79,4 +79,30 @@ public sealed record SyntheticCross(
|
||||
|
||||
/// <summary>The two currencies that are not shared: the ones the sentiment features compare.</summary>
|
||||
public (string Long, string Short) Exposure() => (Symbol[..3], Symbol[3..]);
|
||||
|
||||
/// <summary>
|
||||
/// The distinct currencies of two pairs in order of appearance — <c>EURUSD</c>/<c>USDCHF</c>
|
||||
/// gives EUR, USD, CHF —: what a basket is exposed to, and the flags the interface shows.
|
||||
/// </summary>
|
||||
public static IReadOnlyList<string> Currencies(string a, string b)
|
||||
{
|
||||
List<string> found = [];
|
||||
foreach (string pair in (string[])[a ?? string.Empty, b ?? string.Empty])
|
||||
{
|
||||
if (pair.Length < 6)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
foreach (string c in (string[])[pair[..3].ToUpperInvariant(), pair[3..6].ToUpperInvariant()])
|
||||
{
|
||||
if (!found.Contains(c))
|
||||
{
|
||||
found.Add(c);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return found;
|
||||
}
|
||||
}
|
||||
@@ -2,13 +2,12 @@ using Encelado.Core.Baskets.Data;
|
||||
|
||||
namespace Encelado.Core.Broker;
|
||||
|
||||
/// <summary>Where the orders go. Shown in the window at all times, in colour.</summary>
|
||||
/// <summary>Where the orders go. Shown in the interface at all times, in colour. The values keep the numbers of 5.0 (Paper, 1, is gone).</summary>
|
||||
public enum BrokerEnvironment
|
||||
{
|
||||
Backtest = 0,
|
||||
Paper,
|
||||
Demo,
|
||||
Real,
|
||||
Demo = 2,
|
||||
Real = 3,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
@@ -128,6 +127,13 @@ public sealed record OrderOutcome(
|
||||
new(false, false, orderId, 0, 0, 0, DateTime.UtcNow, 0, "Unknown", error) { RequestedUnits = requestedUnits };
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// What became of a close request. <see cref="RealizedPnl"/> is the net realised result of
|
||||
/// the closed position in account currency (its profit minus its own fees), or NaN when
|
||||
/// the venue has not said it: eToro never says it in the close answer, and the trade
|
||||
/// history settles it later (netProfit − fees). It is never the cash the close returned to
|
||||
/// the account, and NaN is never read as zero.
|
||||
/// </summary>
|
||||
public sealed record CloseOutcome(
|
||||
bool Closed,
|
||||
bool Rejected,
|
||||
@@ -139,6 +145,15 @@ public sealed record CloseOutcome(
|
||||
string Error)
|
||||
{
|
||||
public bool Pending => !Closed && !Rejected;
|
||||
|
||||
/// <summary>The position the close is about; zero when not known.</summary>
|
||||
public long PositionId { get; init; }
|
||||
|
||||
/// <summary>Cash the close returned to the account (margin released plus profit), as eToro's <c>proceeds</c>. Diagnostics only: never a P&L.</summary>
|
||||
public double Proceeds { get; init; } = double.NaN;
|
||||
|
||||
/// <summary>Quote currency → account currency rate the venue applied at the close (1 for USD-quoted pairs); NaN when not given.</summary>
|
||||
public double ConversionRate { get; init; } = double.NaN;
|
||||
}
|
||||
|
||||
/// <summary>What the broker says the order would cost right now, in account currency.</summary>
|
||||
@@ -152,7 +167,11 @@ public sealed record CostEstimate(
|
||||
{
|
||||
}
|
||||
|
||||
/// <summary>A closed trade from the broker's history, for realised P&L and slippage.</summary>
|
||||
/// <summary>
|
||||
/// A closed trade from the broker's history: the P&L of record. <see cref="NetProfit"/>
|
||||
/// has eToro's meaning — the result of the trade <b>before</b> <see cref="Fees"/>, which are
|
||||
/// kept apart — and every simulator follows it.
|
||||
/// </summary>
|
||||
public sealed record ClosedTrade(
|
||||
long PositionId,
|
||||
long InstrumentId,
|
||||
@@ -163,12 +182,15 @@ public sealed record ClosedTrade(
|
||||
DateTime OpenedUtc,
|
||||
DateTime ClosedUtc,
|
||||
double NetProfit,
|
||||
double Fees);
|
||||
double Fees)
|
||||
{
|
||||
/// <summary>The realised result the bot records: netProfit minus fees.</summary>
|
||||
public double NetUsd => NetProfit - Fees;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Everything the engine asks of a venue. Three implementations: the real eToro API,
|
||||
/// the paper simulator (real quotes, local fills) and the backtest replay. The engine
|
||||
/// never knows which one it holds.
|
||||
/// Everything the engine asks of a venue. Two implementations: the real eToro API (demo
|
||||
/// or real account) and the backtest replay. The engine never knows which one it holds.
|
||||
/// </summary>
|
||||
public interface IBroker : IAsyncDisposable
|
||||
{
|
||||
@@ -210,6 +232,7 @@ public interface IBroker : IAsyncDisposable
|
||||
|
||||
Task<CostEstimate?> GetCostAsync(OrderRequest request, CancellationToken ct);
|
||||
|
||||
/// <summary>The positions closed since <paramref name="fromUtc"/> (the venue filters on the closing day, UTC). Throws when the history cannot be read: an unreadable history is never an empty one.</summary>
|
||||
Task<IReadOnlyList<ClosedTrade>> GetClosedTradesAsync(DateTime fromUtc, CancellationToken ct);
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
namespace Encelado.Core.Broker;
|
||||
|
||||
/// <summary>
|
||||
/// The round-trip times of the last minute (or of any window): the last value and the
|
||||
/// mean of the samples younger than the window. Thread-safe; the clock is a monotonic
|
||||
/// millisecond counter (<see cref="Environment.TickCount64"/> unless the caller passes one).
|
||||
/// </summary>
|
||||
public sealed class LatencyWindow(TimeSpan window)
|
||||
{
|
||||
private readonly Lock _gate = new();
|
||||
private readonly Queue<(long At, double Ms)> _samples = new();
|
||||
private double _sum;
|
||||
private double _last = double.NaN;
|
||||
|
||||
public TimeSpan Window { get; } = window;
|
||||
|
||||
/// <summary>The last sample, NaN before the first.</summary>
|
||||
public double Last
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return _last;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public void Add(double milliseconds) => Add(milliseconds, Environment.TickCount64);
|
||||
|
||||
public void Add(double milliseconds, long nowMs)
|
||||
{
|
||||
if (!double.IsFinite(milliseconds) || milliseconds < 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
lock (_gate)
|
||||
{
|
||||
_last = milliseconds;
|
||||
_samples.Enqueue((nowMs, milliseconds));
|
||||
_sum += milliseconds;
|
||||
Trim(nowMs);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Mean of the samples inside the window; NaN when there is none.</summary>
|
||||
public double Average() => Average(Environment.TickCount64);
|
||||
|
||||
public double Average(long nowMs)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
Trim(nowMs);
|
||||
return _samples.Count > 0 ? _sum / _samples.Count : double.NaN;
|
||||
}
|
||||
}
|
||||
|
||||
private void Trim(long nowMs)
|
||||
{
|
||||
long edge = nowMs - (long)Window.TotalMilliseconds;
|
||||
while (_samples.Count > 0 && _samples.Peek().At <= edge)
|
||||
{
|
||||
_sum -= _samples.Dequeue().Ms;
|
||||
}
|
||||
|
||||
if (_samples.Count == 0)
|
||||
{
|
||||
_sum = 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,560 +0,0 @@
|
||||
using System.Globalization;
|
||||
using System.Text;
|
||||
using System.Text.Json;
|
||||
using Encelado.Core.Baskets;
|
||||
using Encelado.Core.Baskets.Data;
|
||||
|
||||
namespace Encelado.Core.Broker;
|
||||
|
||||
/// <summary>Knobs of the local simulator.</summary>
|
||||
public sealed class PaperBrokerOptions
|
||||
{
|
||||
public double StartingBalance { get; set; } = 10_000;
|
||||
|
||||
/// <summary>Slippage charged on every fill, in pips per leg, on top of the real spread.</summary>
|
||||
public double SlippagePips { get; set; } = 0.3;
|
||||
|
||||
/// <summary>Overnight fee per leg per calendar day, in pips, charged at 21:00 UTC. Weekend counts three days.</summary>
|
||||
public double OvernightPipsPerDay { get; set; } = 0.3;
|
||||
|
||||
/// <summary>Where the simulator keeps its positions between runs. Empty = memory only.</summary>
|
||||
public string StatePath { get; set; } = string.Empty;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The paper venue: quotes, instruments, candles and cost estimates come from a real
|
||||
/// broker in read-only use; fills, positions, stops and the account are simulated here,
|
||||
/// at the real bid/ask of the moment plus a configured slippage.
|
||||
/// <para>
|
||||
/// Stops and take-profits are evaluated on every quote refresh, which is the same
|
||||
/// granularity the live engine sees (a poll every few seconds), so a paper session and
|
||||
/// a demo session differ only in who fills the order.
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public sealed class PaperBroker : IBroker
|
||||
{
|
||||
private readonly IBroker _feed;
|
||||
private readonly PaperBrokerOptions _options;
|
||||
private readonly Lock _gate = new();
|
||||
private readonly Dictionary<long, PaperPosition> _positions = [];
|
||||
private readonly Dictionary<long, Instrument> _instruments = [];
|
||||
private readonly Dictionary<long, QuoteSnapshot> _quotes = [];
|
||||
private readonly Dictionary<string, OrderOutcome> _orders = new(StringComparer.OrdinalIgnoreCase);
|
||||
private readonly List<ClosedTrade> _closed = [];
|
||||
private double _balance;
|
||||
private long _nextId = 1;
|
||||
private DateTime _lastOvernightUtc = DateTime.MinValue;
|
||||
|
||||
private sealed class PaperPosition
|
||||
{
|
||||
public long Id;
|
||||
public long InstrumentId;
|
||||
public string Symbol = string.Empty;
|
||||
public bool IsBuy;
|
||||
public double Units;
|
||||
public double OpenRate;
|
||||
public DateTime OpenedUtc;
|
||||
public double StopLoss;
|
||||
public double TakeProfit;
|
||||
public int Leverage;
|
||||
public double Fees;
|
||||
public string ClientRef = string.Empty;
|
||||
}
|
||||
|
||||
public PaperBroker(IBroker feed, PaperBrokerOptions options)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(feed);
|
||||
ArgumentNullException.ThrowIfNull(options);
|
||||
_feed = feed;
|
||||
_options = options;
|
||||
_balance = options.StartingBalance;
|
||||
Load();
|
||||
}
|
||||
|
||||
public BrokerEnvironment Environment => BrokerEnvironment.Paper;
|
||||
|
||||
public string Name => $"paper su {_feed.Name}";
|
||||
|
||||
public bool SupportsTrading => true;
|
||||
|
||||
public TimeSpan ClockSkew => _feed.ClockSkew;
|
||||
|
||||
/// <summary>Raised when the simulator closes a position on its own (stop or take-profit hit).</summary>
|
||||
public event Action<long, string>? PositionClosedByStop;
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Read-only pass-through
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
public async Task<IReadOnlyList<Instrument>> GetInstrumentsAsync(IReadOnlyList<string> symbols, CancellationToken ct)
|
||||
{
|
||||
IReadOnlyList<Instrument> list = await _feed.GetInstrumentsAsync(symbols, ct).ConfigureAwait(false);
|
||||
lock (_gate)
|
||||
{
|
||||
foreach (Instrument i in list)
|
||||
{
|
||||
_instruments[i.Id] = i;
|
||||
}
|
||||
}
|
||||
|
||||
return list;
|
||||
}
|
||||
|
||||
public async Task<IReadOnlyList<QuoteSnapshot>> GetQuotesAsync(IReadOnlyList<long> instrumentIds, CancellationToken ct)
|
||||
{
|
||||
IReadOnlyList<QuoteSnapshot> quotes = await _feed.GetQuotesAsync(instrumentIds, ct).ConfigureAwait(false);
|
||||
MarkToMarket(quotes);
|
||||
return quotes;
|
||||
}
|
||||
|
||||
public Task<IReadOnlyList<BidAskBar>> GetCandlesAsync(long instrumentId, TimeSpan interval, int count, CancellationToken ct) =>
|
||||
_feed.GetCandlesAsync(instrumentId, interval, count, ct);
|
||||
|
||||
public Task<CostEstimate?> GetCostAsync(OrderRequest request, CancellationToken ct) => _feed.GetCostAsync(request, ct);
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Simulation
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
/// <summary>Feeds fresh quotes to the simulator: updates P&L and triggers stops. Called by <see cref="GetQuotesAsync"/> too.</summary>
|
||||
public void MarkToMarket(IReadOnlyList<QuoteSnapshot> quotes)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(quotes);
|
||||
List<(long Id, string Reason)> hit = [];
|
||||
lock (_gate)
|
||||
{
|
||||
foreach (QuoteSnapshot q in quotes)
|
||||
{
|
||||
if (q.IsValid)
|
||||
{
|
||||
_quotes[q.InstrumentId] = q;
|
||||
}
|
||||
}
|
||||
|
||||
ChargeOvernight(DateTime.UtcNow);
|
||||
|
||||
foreach (PaperPosition p in _positions.Values)
|
||||
{
|
||||
if (!_quotes.TryGetValue(p.InstrumentId, out QuoteSnapshot q) || !q.IsValid)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
double exit = p.IsBuy ? q.Bid : q.Ask;
|
||||
if (p.StopLoss > 0 && (p.IsBuy ? exit <= p.StopLoss : exit >= p.StopLoss))
|
||||
{
|
||||
hit.Add((p.Id, "stop nativo"));
|
||||
}
|
||||
else if (p.TakeProfit > 0 && (p.IsBuy ? exit >= p.TakeProfit : exit <= p.TakeProfit))
|
||||
{
|
||||
hit.Add((p.Id, "take-profit nativo"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
foreach ((long id, string reason) in hit)
|
||||
{
|
||||
CloseInternal(id, reason);
|
||||
PositionClosedByStop?.Invoke(id, reason);
|
||||
}
|
||||
}
|
||||
|
||||
public Task<AccountSnapshot> GetAccountAsync(CancellationToken ct)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
double unrealized = 0;
|
||||
double margin = 0;
|
||||
foreach (PaperPosition p in _positions.Values)
|
||||
{
|
||||
unrealized += UnrealizedUsd(p);
|
||||
margin += MarginUsd(p);
|
||||
}
|
||||
|
||||
double equity = _balance + unrealized;
|
||||
return Task.FromResult(new AccountSnapshot(DateTime.UtcNow, "USD", _balance, equity, Math.Max(0, equity - margin), margin, unrealized));
|
||||
}
|
||||
}
|
||||
|
||||
public Task<IReadOnlyList<BrokerPosition>> GetPositionsAsync(CancellationToken ct)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
List<BrokerPosition> list = new(_positions.Count);
|
||||
foreach (PaperPosition p in _positions.Values)
|
||||
{
|
||||
double current = _quotes.TryGetValue(p.InstrumentId, out QuoteSnapshot q) && q.IsValid ? (p.IsBuy ? q.Bid : q.Ask) : p.OpenRate;
|
||||
list.Add(new BrokerPosition(p.Id, p.InstrumentId, p.IsBuy, p.Units, p.OpenRate, p.OpenedUtc, p.StopLoss, p.TakeProfit, p.Leverage, MarginUsd(p), UnrealizedUsd(p), p.Fees, current));
|
||||
}
|
||||
|
||||
return Task.FromResult<IReadOnlyList<BrokerPosition>>(list);
|
||||
}
|
||||
}
|
||||
|
||||
public Task<OrderOutcome> OpenAsync(OrderRequest request, CancellationToken ct)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(request);
|
||||
lock (_gate)
|
||||
{
|
||||
if (_orders.TryGetValue(request.ClientRef, out OrderOutcome? already))
|
||||
{
|
||||
return Task.FromResult(already);
|
||||
}
|
||||
|
||||
if (!_instruments.TryGetValue(request.InstrumentId, out Instrument? instrument))
|
||||
{
|
||||
return Task.FromResult(Reject(request, "strumento sconosciuto al simulatore: chiama GetInstrumentsAsync prima"));
|
||||
}
|
||||
|
||||
if (!_quotes.TryGetValue(request.InstrumentId, out QuoteSnapshot q) || !q.IsValid)
|
||||
{
|
||||
return Task.FromResult(Reject(request, "nessuna quotazione valida per lo strumento"));
|
||||
}
|
||||
|
||||
if (request.Units <= 0 || request.Units < instrument.MinUnits)
|
||||
{
|
||||
return Task.FromResult(Reject(request, $"unità {request.Units} sotto il minimo {instrument.MinUnits}"));
|
||||
}
|
||||
|
||||
if (instrument.MaxUnitsPerOrder > 0 && request.Units > instrument.MaxUnitsPerOrder)
|
||||
{
|
||||
return Task.FromResult(Reject(request, $"unità {request.Units} sopra il massimo per ordine {instrument.MaxUnitsPerOrder}"));
|
||||
}
|
||||
|
||||
if (!request.IsBuy && request.StopLossRate is null)
|
||||
{
|
||||
return Task.FromResult(Reject(request, "eToro richiede uno stop per le vendite allo scoperto"));
|
||||
}
|
||||
|
||||
double slip = _options.SlippagePips * instrument.Pip;
|
||||
double fill = instrument.RoundPrice(request.IsBuy ? q.Ask + slip : q.Bid - slip);
|
||||
|
||||
double? mid(string s) => MidOf(s);
|
||||
double notional = PipMath.NotionalUsd(instrument.Symbol, request.Units, fill, mid);
|
||||
if (double.IsNaN(notional))
|
||||
{
|
||||
return Task.FromResult(Reject(request, "impossibile convertire il nozionale in USD: manca la coppia di conversione"));
|
||||
}
|
||||
|
||||
if (notional < instrument.MinExposure)
|
||||
{
|
||||
return Task.FromResult(Reject(request, string.Create(CultureInfo.InvariantCulture, $"esposizione {notional:F0} USD sotto il minimo {instrument.MinExposure:F0}")));
|
||||
}
|
||||
|
||||
double margin = notional / Math.Max(1, request.Leverage);
|
||||
double available = AvailableLocked();
|
||||
if (margin > available)
|
||||
{
|
||||
return Task.FromResult(Reject(request, string.Create(CultureInfo.InvariantCulture, $"margine richiesto {margin:F2} USD oltre il disponibile {available:F2}")));
|
||||
}
|
||||
|
||||
PaperPosition p = new()
|
||||
{
|
||||
Id = _nextId++,
|
||||
InstrumentId = request.InstrumentId,
|
||||
Symbol = instrument.Symbol,
|
||||
IsBuy = request.IsBuy,
|
||||
Units = request.Units,
|
||||
OpenRate = fill,
|
||||
OpenedUtc = DateTime.UtcNow,
|
||||
StopLoss = request.StopLossRate ?? 0,
|
||||
TakeProfit = request.TakeProfitRate ?? 0,
|
||||
Leverage = Math.Max(1, request.Leverage),
|
||||
ClientRef = request.ClientRef,
|
||||
};
|
||||
_positions[p.Id] = p;
|
||||
|
||||
OrderOutcome outcome = new(true, false, p.Id, p.Id, fill, request.Units, p.OpenedUtc, 0, "Filled", string.Empty);
|
||||
_orders[request.ClientRef] = outcome;
|
||||
Save();
|
||||
return Task.FromResult(outcome);
|
||||
}
|
||||
}
|
||||
|
||||
public Task<OrderOutcome?> LookupOrderAsync(string clientRef, CancellationToken ct)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return Task.FromResult(_orders.TryGetValue(clientRef, out OrderOutcome? o) ? o : null);
|
||||
}
|
||||
}
|
||||
|
||||
public Task<OrderOutcome?> LookupOrderByIdAsync(long orderId, CancellationToken ct)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return Task.FromResult(_orders.Values.FirstOrDefault(o => o.OrderId == orderId));
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The simulator fills at once: there is never an order to cancel.</summary>
|
||||
public Task<bool> CancelOrderAsync(long orderId, CancellationToken ct) => Task.FromResult(false);
|
||||
|
||||
public Task<CloseOutcome> CloseAsync(long positionId, long instrumentId, CancellationToken ct)
|
||||
{
|
||||
CloseOutcome? outcome = CloseInternal(positionId, "chiusura richiesta");
|
||||
return Task.FromResult(outcome ?? new CloseOutcome(false, true, 0, 0, 0, DateTime.UtcNow, 0, $"posizione {positionId} non trovata"));
|
||||
}
|
||||
|
||||
public Task<bool> UpdateStopsAsync(long positionId, double? stopLoss, double? takeProfit, CancellationToken ct)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
if (!_positions.TryGetValue(positionId, out PaperPosition? p))
|
||||
{
|
||||
return Task.FromResult(false);
|
||||
}
|
||||
|
||||
if (stopLoss is { } sl)
|
||||
{
|
||||
p.StopLoss = sl;
|
||||
}
|
||||
|
||||
if (takeProfit is { } tp)
|
||||
{
|
||||
p.TakeProfit = tp;
|
||||
}
|
||||
|
||||
Save();
|
||||
return Task.FromResult(true);
|
||||
}
|
||||
}
|
||||
|
||||
public Task<IReadOnlyList<ClosedTrade>> GetClosedTradesAsync(DateTime fromUtc, CancellationToken ct)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return Task.FromResult<IReadOnlyList<ClosedTrade>>([.. _closed.Where(c => c.ClosedUtc >= fromUtc)]);
|
||||
}
|
||||
}
|
||||
|
||||
private CloseOutcome? CloseInternal(long positionId, string reason)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
if (!_positions.Remove(positionId, out PaperPosition? p))
|
||||
{
|
||||
return null;
|
||||
}
|
||||
|
||||
if (!_quotes.TryGetValue(p.InstrumentId, out QuoteSnapshot q) || !q.IsValid)
|
||||
{
|
||||
_positions[positionId] = p;
|
||||
return new CloseOutcome(false, true, 0, 0, 0, DateTime.UtcNow, 0, "nessuna quotazione valida per chiudere");
|
||||
}
|
||||
|
||||
Instrument instrument = _instruments[p.InstrumentId];
|
||||
double slip = _options.SlippagePips * instrument.Pip;
|
||||
double exit = instrument.RoundPrice(p.IsBuy ? q.Bid - slip : q.Ask + slip);
|
||||
double pnl = PipMath.LegPnlUsd(p.Symbol, p.IsBuy, p.Units, p.OpenRate, exit, MidOf);
|
||||
if (double.IsNaN(pnl))
|
||||
{
|
||||
pnl = 0;
|
||||
}
|
||||
|
||||
pnl -= p.Fees;
|
||||
_balance += pnl;
|
||||
DateTime now = DateTime.UtcNow;
|
||||
_closed.Add(new ClosedTrade(p.Id, p.InstrumentId, p.IsBuy, p.Units, p.OpenRate, exit, p.OpenedUtc, now, pnl, p.Fees));
|
||||
Save();
|
||||
return new CloseOutcome(true, false, _nextId++, exit, p.Units, now, pnl, reason);
|
||||
}
|
||||
}
|
||||
|
||||
private OrderOutcome Reject(OrderRequest request, string why)
|
||||
{
|
||||
OrderOutcome o = new(false, true, 0, 0, 0, request.Units, DateTime.UtcNow, 0, "Rejected", why);
|
||||
_orders[request.ClientRef] = o;
|
||||
return o;
|
||||
}
|
||||
|
||||
private double AvailableLocked()
|
||||
{
|
||||
double unrealized = 0;
|
||||
double margin = 0;
|
||||
foreach (PaperPosition p in _positions.Values)
|
||||
{
|
||||
unrealized += UnrealizedUsd(p);
|
||||
margin += MarginUsd(p);
|
||||
}
|
||||
|
||||
return Math.Max(0, _balance + unrealized - margin);
|
||||
}
|
||||
|
||||
private double UnrealizedUsd(PaperPosition p)
|
||||
{
|
||||
if (!_quotes.TryGetValue(p.InstrumentId, out QuoteSnapshot q) || !q.IsValid)
|
||||
{
|
||||
return -p.Fees;
|
||||
}
|
||||
|
||||
double exit = p.IsBuy ? q.Bid : q.Ask;
|
||||
double pnl = PipMath.LegPnlUsd(p.Symbol, p.IsBuy, p.Units, p.OpenRate, exit, MidOf);
|
||||
return (double.IsNaN(pnl) ? 0 : pnl) - p.Fees;
|
||||
}
|
||||
|
||||
private double MarginUsd(PaperPosition p)
|
||||
{
|
||||
double notional = PipMath.NotionalUsd(p.Symbol, p.Units, p.OpenRate, MidOf);
|
||||
return (double.IsNaN(notional) ? 0 : notional) / Math.Max(1, p.Leverage);
|
||||
}
|
||||
|
||||
private double? MidOf(string symbol)
|
||||
{
|
||||
foreach ((long id, Instrument i) in _instruments)
|
||||
{
|
||||
if (i.Symbol.Equals(symbol, StringComparison.OrdinalIgnoreCase) && _quotes.TryGetValue(id, out QuoteSnapshot q) && q.IsValid)
|
||||
{
|
||||
return q.Mid;
|
||||
}
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary>Overnight fee once per calendar day at 21:00 UTC; Friday counts for three nights.</summary>
|
||||
private void ChargeOvernight(DateTime now)
|
||||
{
|
||||
DateTime today21 = new(now.Year, now.Month, now.Day, 21, 0, 0, DateTimeKind.Utc);
|
||||
if (now < today21 || _lastOvernightUtc >= today21 || _positions.Count == 0)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
int nights = now.DayOfWeek == DayOfWeek.Friday ? 3 : 1;
|
||||
foreach (PaperPosition p in _positions.Values)
|
||||
{
|
||||
if (p.OpenedUtc >= today21)
|
||||
{
|
||||
continue;
|
||||
}
|
||||
|
||||
double pipUsd = PipMath.PipValueUsd(p.Symbol, p.Units, MidOf);
|
||||
if (!double.IsNaN(pipUsd))
|
||||
{
|
||||
p.Fees += _options.OvernightPipsPerDay * nights * pipUsd;
|
||||
}
|
||||
}
|
||||
|
||||
_lastOvernightUtc = today21;
|
||||
Save();
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Persistence (JSON, atomic)
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
private void Save()
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(_options.StatePath))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
string full = Path.GetFullPath(_options.StatePath);
|
||||
Directory.CreateDirectory(Path.GetDirectoryName(full)!);
|
||||
using MemoryStream ms = new();
|
||||
using (Utf8JsonWriter w = new(ms, new JsonWriterOptions { Indented = true }))
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("balance", _balance);
|
||||
w.WriteNumber("nextId", _nextId);
|
||||
w.WriteString("lastOvernightUtc", _lastOvernightUtc.ToString("O", CultureInfo.InvariantCulture));
|
||||
w.WriteStartArray("positions");
|
||||
foreach (PaperPosition p in _positions.Values)
|
||||
{
|
||||
w.WriteStartObject();
|
||||
w.WriteNumber("id", p.Id);
|
||||
w.WriteNumber("instrumentId", p.InstrumentId);
|
||||
w.WriteString("symbol", p.Symbol);
|
||||
w.WriteBoolean("isBuy", p.IsBuy);
|
||||
w.WriteNumber("units", p.Units);
|
||||
w.WriteNumber("openRate", p.OpenRate);
|
||||
w.WriteString("openedUtc", p.OpenedUtc.ToString("O", CultureInfo.InvariantCulture));
|
||||
w.WriteNumber("stopLoss", p.StopLoss);
|
||||
w.WriteNumber("takeProfit", p.TakeProfit);
|
||||
w.WriteNumber("leverage", p.Leverage);
|
||||
w.WriteNumber("fees", p.Fees);
|
||||
w.WriteString("clientRef", p.ClientRef);
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
w.WriteEndArray();
|
||||
w.WriteEndObject();
|
||||
}
|
||||
|
||||
File.WriteAllBytes(full + ".tmp", ms.ToArray());
|
||||
File.Move(full + ".tmp", full, overwrite: true);
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
|
||||
{
|
||||
// The simulator keeps working in memory; the engine logs the account state anyway.
|
||||
}
|
||||
}
|
||||
|
||||
private void Load()
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(_options.StatePath) || !File.Exists(_options.StatePath))
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(File.ReadAllBytes(_options.StatePath));
|
||||
JsonElement root = doc.RootElement;
|
||||
_balance = root.TryGetProperty("balance", out JsonElement b) ? b.GetDouble() : _balance;
|
||||
_nextId = root.TryGetProperty("nextId", out JsonElement n) ? n.GetInt64() : 1;
|
||||
if (root.TryGetProperty("lastOvernightUtc", out JsonElement lo) &&
|
||||
DateTime.TryParse(lo.GetString(), CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out DateTime t))
|
||||
{
|
||||
_lastOvernightUtc = t;
|
||||
}
|
||||
|
||||
if (root.TryGetProperty("positions", out JsonElement arr))
|
||||
{
|
||||
foreach (JsonElement e in arr.EnumerateArray())
|
||||
{
|
||||
PaperPosition p = new()
|
||||
{
|
||||
Id = e.GetProperty("id").GetInt64(),
|
||||
InstrumentId = e.GetProperty("instrumentId").GetInt64(),
|
||||
Symbol = e.GetProperty("symbol").GetString() ?? string.Empty,
|
||||
IsBuy = e.GetProperty("isBuy").GetBoolean(),
|
||||
Units = e.GetProperty("units").GetDouble(),
|
||||
OpenRate = e.GetProperty("openRate").GetDouble(),
|
||||
OpenedUtc = DateTime.Parse(e.GetProperty("openedUtc").GetString()!, CultureInfo.InvariantCulture, DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal),
|
||||
StopLoss = e.GetProperty("stopLoss").GetDouble(),
|
||||
TakeProfit = e.GetProperty("takeProfit").GetDouble(),
|
||||
Leverage = e.GetProperty("leverage").GetInt32(),
|
||||
Fees = e.GetProperty("fees").GetDouble(),
|
||||
ClientRef = e.TryGetProperty("clientRef", out JsonElement cr) ? cr.GetString() ?? string.Empty : string.Empty,
|
||||
};
|
||||
_positions[p.Id] = p;
|
||||
}
|
||||
}
|
||||
}
|
||||
catch (Exception ex) when (ex is IOException or JsonException or KeyNotFoundException or InvalidOperationException)
|
||||
{
|
||||
// A corrupt state file starts the simulator fresh rather than crashing the bot.
|
||||
}
|
||||
}
|
||||
|
||||
public string Describe()
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
StringBuilder sb = new();
|
||||
sb.Append(CultureInfo.InvariantCulture, $"paper: saldo {_balance:F2} USD, {_positions.Count} posizioni");
|
||||
return sb.ToString();
|
||||
}
|
||||
}
|
||||
|
||||
public ValueTask DisposeAsync()
|
||||
{
|
||||
Save();
|
||||
return ValueTask.CompletedTask;
|
||||
}
|
||||
}
|
||||
@@ -1,5 +1,16 @@
|
||||
namespace Encelado.Core.Broker;
|
||||
|
||||
/// <summary>
|
||||
/// One quota class as the diagnostics show it: calls in the current window against the
|
||||
/// budget, the pause a 429 imposed (null when none is running) and how many 429 the venue
|
||||
/// answered since the start.
|
||||
/// </summary>
|
||||
public sealed record QuotaUsage(string Name, int Used, int Limit, double WindowSeconds, DateTime? PausedUntilUtc, long Count429)
|
||||
{
|
||||
/// <summary>Used over the budget, 0..1 (more when a burst overran it).</summary>
|
||||
public double UsedFraction => Limit > 0 ? (double)Used / Limit : 0;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A sliding-window request budget: at most <see cref="Limit"/> calls in any
|
||||
/// <see cref="Window"/>. One instance per quota class the venue enforces, because the
|
||||
@@ -15,6 +26,7 @@ public sealed class RateLimiter(int limit, TimeSpan window, string name = "")
|
||||
private readonly Queue<long> _stamps = new();
|
||||
private readonly SemaphoreSlim _gate = new(1, 1);
|
||||
private long _pausedUntil;
|
||||
private long _count429;
|
||||
|
||||
public int Limit { get; } = Math.Max(1, limit);
|
||||
|
||||
@@ -35,6 +47,22 @@ public sealed class RateLimiter(int limit, TimeSpan window, string name = "")
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>How many times the venue answered 429 on this class (each one calls <see cref="Pause"/>).</summary>
|
||||
public long Count429 => Interlocked.Read(ref _count429);
|
||||
|
||||
/// <summary>Until when every caller waits because of a 429; null when no pause is running.</summary>
|
||||
public DateTime? PausedUntilUtc
|
||||
{
|
||||
get
|
||||
{
|
||||
long left = Volatile.Read(ref _pausedUntil) - Environment.TickCount64;
|
||||
return left > 0 ? DateTime.UtcNow.AddMilliseconds(left) : null;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The picture of this class for the diagnostics page.</summary>
|
||||
public QuotaUsage Usage() => new(Name, Used, Limit, Window.TotalSeconds, PausedUntilUtc, Count429);
|
||||
|
||||
/// <summary>Waits until a call fits in the budget, then records it.</summary>
|
||||
public async Task WaitAsync(CancellationToken ct)
|
||||
{
|
||||
@@ -76,6 +104,7 @@ public sealed class RateLimiter(int limit, TimeSpan window, string name = "")
|
||||
/// <summary>The venue said 429: hold every caller for <paramref name="retryAfter"/>.</summary>
|
||||
public void Pause(TimeSpan retryAfter)
|
||||
{
|
||||
Interlocked.Increment(ref _count429);
|
||||
long until = Environment.TickCount64 + (long)Math.Max(1000, retryAfter.TotalMilliseconds);
|
||||
long current = Volatile.Read(ref _pausedUntil);
|
||||
if (until > current)
|
||||
|
||||
@@ -62,6 +62,15 @@ public sealed class SentimentEngine
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The retained items, newest first, at most <paramref name="max"/>: a copy (the items are immutable), for the market page.</summary>
|
||||
public IReadOnlyList<ScoredItem> Recent(int max)
|
||||
{
|
||||
lock (_gate)
|
||||
{
|
||||
return [.. _items.OrderByDescending(static i => i.Item.PublishedUtc).Take(Math.Max(0, max))];
|
||||
}
|
||||
}
|
||||
|
||||
public void Forget(DateTime nowUtc)
|
||||
{
|
||||
lock (_gate)
|
||||
|
||||
@@ -26,6 +26,13 @@ public interface INotifier
|
||||
/// <summary>One line for the dashboard: last delivery, queue length, last error.</summary>
|
||||
string Status { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Whether a message queued now would be delivered somewhere. The engine skips the
|
||||
/// work of composing the scheduled messages (hourly status, daily summary) when it
|
||||
/// is false; it can change at any moment, when the channel is switched on or off.
|
||||
/// </summary>
|
||||
bool IsActive { get; }
|
||||
|
||||
/// <summary>Queues a message. Returns at once; delivery is the channel's business.</summary>
|
||||
void Notify(NotificationKind kind, string title, string text);
|
||||
}
|
||||
@@ -37,6 +44,8 @@ public sealed class NullNotifier : INotifier
|
||||
|
||||
public string Status => "notifiche non configurate";
|
||||
|
||||
public bool IsActive => false;
|
||||
|
||||
public void Notify(NotificationKind kind, string title, string text)
|
||||
{
|
||||
// Nothing to deliver to.
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
using System.Globalization;
|
||||
|
||||
namespace Encelado.Core.Notifications;
|
||||
|
||||
/// <summary>
|
||||
/// The one notifier the engine and the host hold for the whole process, whatever the
|
||||
/// settings say from one minute to the next (5.1, hot apply). Behind it sits either
|
||||
/// nothing (<see cref="NullNotifier"/>) or a <see cref="TelegramNotifier"/>, swapped by
|
||||
/// <see cref="ReconfigureAsync"/> after every change of the Telegram settings or of the
|
||||
/// token: switched on, switched off, a new token (a new channel), commands started or
|
||||
/// stopped. The token never sits in the shared configuration: the hub reads it from
|
||||
/// <c>token</c> (the encrypted store) and hands it only to the channel's private copy of
|
||||
/// the options.
|
||||
/// </summary>
|
||||
public sealed class NotifierHub : INotifier, IAsyncDisposable
|
||||
{
|
||||
private readonly TelegramOptions _shared;
|
||||
private readonly Func<string> _token;
|
||||
private readonly Action<string> _log;
|
||||
private readonly Func<TelegramOptions, TelegramNotifier> _factory;
|
||||
private readonly SemaphoreSlim _gate = new(1, 1);
|
||||
private volatile INotifier _inner = NullNotifier.Instance;
|
||||
private TelegramNotifier? _telegram;
|
||||
private TelegramOptions? _options;
|
||||
private string _tokenInUse = string.Empty;
|
||||
private Func<string, CancellationToken, Task<string>>? _commandHandler;
|
||||
|
||||
/// <param name="shared">The configuration's Telegram section: read at every reconfiguration, never written.</param>
|
||||
/// <param name="token">The bot token from the secret store; empty when none is saved.</param>
|
||||
/// <param name="log">Where the hub says what it switched.</param>
|
||||
/// <param name="factory">Builds the channel (the tests pass a fake transport).</param>
|
||||
public NotifierHub(TelegramOptions shared, Func<string> token, Action<string>? log = null, Func<TelegramOptions, TelegramNotifier>? factory = null)
|
||||
{
|
||||
_shared = shared ?? throw new ArgumentNullException(nameof(shared));
|
||||
_token = token ?? throw new ArgumentNullException(nameof(token));
|
||||
_log = log ?? (static _ => { });
|
||||
_factory = factory ?? (o => new TelegramNotifier(o, null, _log));
|
||||
}
|
||||
|
||||
/// <summary>Answers a command from the authorised chat; handed to every channel the hub builds.</summary>
|
||||
public Func<string, CancellationToken, Task<string>>? CommandHandler
|
||||
{
|
||||
get => _commandHandler;
|
||||
set
|
||||
{
|
||||
_commandHandler = value;
|
||||
if (_telegram is { } t)
|
||||
{
|
||||
t.CommandHandler = value;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The live Telegram channel, or null when Telegram is off (for the diagnostics page).</summary>
|
||||
public TelegramNotifier? Telegram => _telegram;
|
||||
|
||||
public bool IsActive => _inner.IsActive;
|
||||
|
||||
public string Status
|
||||
{
|
||||
get
|
||||
{
|
||||
if (_telegram is { } t)
|
||||
{
|
||||
return t.Status;
|
||||
}
|
||||
|
||||
return _shared.Enabled
|
||||
? "Telegram attivo nelle impostazioni ma senza token o chat id: nessun messaggio parte"
|
||||
: NullNotifier.Instance.Status;
|
||||
}
|
||||
}
|
||||
|
||||
public void Notify(NotificationKind kind, string title, string text) => _inner.Notify(kind, title, text);
|
||||
|
||||
/// <summary>The channel's settings, token presence, counters and last error (the diagnostics page and the tick).</summary>
|
||||
public TelegramStatus Describe()
|
||||
{
|
||||
TelegramNotifier? t = _telegram;
|
||||
bool token = (_token() ?? string.Empty).Trim().Length > 0;
|
||||
string chat = _shared.ChatId ?? string.Empty;
|
||||
return new TelegramStatus(
|
||||
token && chat.Length > 0,
|
||||
_shared.Enabled,
|
||||
t is { IsActive: true },
|
||||
_shared.Commands,
|
||||
t?.CommandsRunning ?? false,
|
||||
_shared.HourlyStatus,
|
||||
_shared.EventAlerts,
|
||||
_shared.DailySummaryUtcHour,
|
||||
chat,
|
||||
t?.Queued ?? 0,
|
||||
t?.Sent ?? 0,
|
||||
t?.Failed ?? 0,
|
||||
t?.LastDeliveredUtc,
|
||||
t?.LastError ?? string.Empty);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Brings the channel in line with the settings and the stored token: builds, replaces
|
||||
/// or drops the Telegram channel, and starts or stops its command poller. Cheap when
|
||||
/// nothing changed; safe to call from any thread.
|
||||
/// </summary>
|
||||
public async Task ReconfigureAsync()
|
||||
{
|
||||
await _gate.WaitAsync().ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
string token = (_token() ?? string.Empty).Trim();
|
||||
TelegramOptions wanted = new() { BotToken = token };
|
||||
wanted.CopySettingsFrom(_shared);
|
||||
|
||||
if (!wanted.IsUsable)
|
||||
{
|
||||
if (_telegram is { } old)
|
||||
{
|
||||
_inner = NullNotifier.Instance;
|
||||
_telegram = null;
|
||||
_options = null;
|
||||
_tokenInUse = string.Empty;
|
||||
await old.DisposeAsync().ConfigureAwait(false);
|
||||
_log(wanted.Enabled ? "Telegram spento: manca il token o il chat id" : "Telegram spento dalle impostazioni");
|
||||
}
|
||||
else if (wanted.Enabled)
|
||||
{
|
||||
_log("Telegram attivo nelle impostazioni ma senza token o chat id: notifiche disattivate");
|
||||
}
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
if (_telegram is { } current && !token.Equals(_tokenInUse, StringComparison.Ordinal))
|
||||
{
|
||||
// A new token is a new bot: a new channel, the old one drained and closed.
|
||||
_inner = NullNotifier.Instance;
|
||||
_telegram = null;
|
||||
_options = null;
|
||||
await current.DisposeAsync().ConfigureAwait(false);
|
||||
}
|
||||
|
||||
if (_telegram is null)
|
||||
{
|
||||
_options = wanted;
|
||||
TelegramNotifier created = _factory(_options);
|
||||
created.CommandHandler = _commandHandler;
|
||||
_telegram = created;
|
||||
_tokenInUse = token;
|
||||
_inner = created;
|
||||
_log(string.Create(CultureInfo.InvariantCulture, $"Telegram attivo: chat {wanted.ChatId}, stato orario {(wanted.HourlyStatus ? "sì" : "no")}, eventi {(wanted.EventAlerts ? "sì" : "no")}, riepilogo alle {wanted.DailySummaryUtcHour:00}:00 UTC, comandi {(wanted.Commands ? "sì" : "no")}"));
|
||||
}
|
||||
else
|
||||
{
|
||||
// Same bot: the channel reads its options live, so a new chat id or switch applies at once.
|
||||
_options!.CopySettingsFrom(_shared);
|
||||
}
|
||||
|
||||
if (_options!.Commands)
|
||||
{
|
||||
_telegram.StartCommands();
|
||||
}
|
||||
else if (_telegram.CommandsRunning)
|
||||
{
|
||||
await _telegram.StopCommandsAsync().ConfigureAwait(false);
|
||||
_log("Telegram: comandi dalla chat spenti");
|
||||
}
|
||||
}
|
||||
finally
|
||||
{
|
||||
_gate.Release();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>One test message to the configured chat, delivered now (not queued): the settings page shows the outcome.</summary>
|
||||
public async Task<(bool Ok, string Message)> SendTestAsync(CancellationToken ct)
|
||||
{
|
||||
TelegramNotifier? t = _telegram;
|
||||
if (t is null)
|
||||
{
|
||||
return (false, _shared.Enabled ? "Telegram non è pronto: manca il token o il chat id" : "Telegram è spento nelle impostazioni");
|
||||
}
|
||||
|
||||
string text = TelegramNotifier.Compose(NotificationKind.Event, "Messaggio di prova", string.Create(CultureInfo.InvariantCulture, $"Encelado ti scrive dalla pagina Impostazioni ({DateTime.UtcNow:yyyy-MM-dd HH:mm:ss} UTC)."));
|
||||
bool ok = await t.DeliverAsync(text, ct).ConfigureAwait(false);
|
||||
return ok ? (true, "messaggio di prova consegnato") : (false, $"messaggio di prova non consegnato: {t.LastError}");
|
||||
}
|
||||
|
||||
public async ValueTask DisposeAsync()
|
||||
{
|
||||
await _gate.WaitAsync().ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
_inner = NullNotifier.Instance;
|
||||
if (_telegram is { } t)
|
||||
{
|
||||
_telegram = null;
|
||||
await t.DisposeAsync().ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
finally
|
||||
{
|
||||
_gate.Release();
|
||||
}
|
||||
|
||||
_gate.Dispose();
|
||||
}
|
||||
}
|
||||
@@ -11,10 +11,14 @@ public sealed class TelegramOptions
|
||||
{
|
||||
public bool Enabled { get; set; }
|
||||
|
||||
/// <summary>From <c>TELEGRAM_BOT_TOKEN</c>; never in a file of the repository.</summary>
|
||||
/// <summary>
|
||||
/// The bot's token. Never in a file and never in the shared configuration: it lives
|
||||
/// encrypted in the secret store, and only the private copy handed to the channel
|
||||
/// carries it (see <see cref="NotifierHub"/>).
|
||||
/// </summary>
|
||||
public string BotToken { get; set; } = string.Empty;
|
||||
|
||||
/// <summary>The one chat the bot talks to and listens to (<c>TELEGRAM_CHAT_ID</c> or <c>notifications.telegram.chatId</c>).</summary>
|
||||
/// <summary>The one chat the bot talks to and listens to (<c>notifications.telegram.chatId</c>).</summary>
|
||||
public string ChatId { get; set; } = string.Empty;
|
||||
|
||||
public bool HourlyStatus { get; set; } = true;
|
||||
@@ -30,6 +34,19 @@ public sealed class TelegramOptions
|
||||
public string BaseUrl { get; set; } = "https://api.telegram.org";
|
||||
|
||||
public bool IsUsable => Enabled && BotToken.Length > 0 && ChatId.Length > 0;
|
||||
|
||||
/// <summary>Copies every field but the token (which the caller decides) from <paramref name="source"/>.</summary>
|
||||
public void CopySettingsFrom(TelegramOptions source)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(source);
|
||||
Enabled = source.Enabled;
|
||||
ChatId = source.ChatId;
|
||||
HourlyStatus = source.HourlyStatus;
|
||||
EventAlerts = source.EventAlerts;
|
||||
DailySummaryUtcHour = source.DailySummaryUtcHour;
|
||||
Commands = source.Commands;
|
||||
BaseUrl = source.BaseUrl;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
@@ -49,7 +66,9 @@ public sealed class TelegramNotifier : INotifier, IAsyncDisposable
|
||||
private readonly Channel<(NotificationKind Kind, string Title, string Text)> _queue = Channel.CreateBounded<(NotificationKind, string, string)>(new BoundedChannelOptions(500) { FullMode = BoundedChannelFullMode.DropOldest });
|
||||
private readonly CancellationTokenSource _cts = new();
|
||||
private readonly Task _sender;
|
||||
private readonly Lock _pollGate = new();
|
||||
private Task? _poller;
|
||||
private CancellationTokenSource? _pollCts;
|
||||
private DateTime _lastSentUtc = DateTime.MinValue;
|
||||
private DateTime? _lastDeliveredUtc;
|
||||
private string _lastError = string.Empty;
|
||||
@@ -85,6 +104,26 @@ public sealed class TelegramNotifier : INotifier, IAsyncDisposable
|
||||
|
||||
public int Failed => _failed;
|
||||
|
||||
/// <summary>When Telegram last accepted a message; null before the first.</summary>
|
||||
public DateTime? LastDeliveredUtc => _lastDeliveredUtc;
|
||||
|
||||
/// <summary>The last error Telegram or the network gave, or empty after a success.</summary>
|
||||
public string LastError => _lastError;
|
||||
|
||||
/// <summary>Whether the long-polling task for the commands is running.</summary>
|
||||
public bool CommandsRunning
|
||||
{
|
||||
get
|
||||
{
|
||||
lock (_pollGate)
|
||||
{
|
||||
return _poller is { IsCompleted: false };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public bool IsActive => _options.IsUsable;
|
||||
|
||||
public string Status
|
||||
{
|
||||
get
|
||||
@@ -119,15 +158,92 @@ public sealed class TelegramNotifier : INotifier, IAsyncDisposable
|
||||
_queue.Writer.TryWrite((kind, title ?? string.Empty, text ?? string.Empty));
|
||||
}
|
||||
|
||||
/// <summary>Starts the single long-polling task, when commands are enabled.</summary>
|
||||
/// <summary>Starts the single long-polling task, when commands are enabled and it is not running already.</summary>
|
||||
public void StartCommands()
|
||||
{
|
||||
if (_options.IsUsable && _options.Commands && _poller is null)
|
||||
lock (_pollGate)
|
||||
{
|
||||
_poller = Task.Run(PollLoopAsync);
|
||||
if (!_options.IsUsable || !_options.Commands || _poller is { IsCompleted: false } || _cts.IsCancellationRequested)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
_pollCts?.Dispose();
|
||||
_pollCts = CancellationTokenSource.CreateLinkedTokenSource(_cts.Token);
|
||||
CancellationToken token = _pollCts.Token;
|
||||
_poller = Task.Run(() => PollLoopAsync(token));
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Stops the long-polling task (commands switched off in the settings); sending goes on.</summary>
|
||||
public async Task StopCommandsAsync()
|
||||
{
|
||||
Task? poller;
|
||||
CancellationTokenSource? cts;
|
||||
lock (_pollGate)
|
||||
{
|
||||
poller = _poller;
|
||||
cts = _pollCts;
|
||||
_poller = null;
|
||||
_pollCts = null;
|
||||
}
|
||||
|
||||
if (cts is null)
|
||||
{
|
||||
return;
|
||||
}
|
||||
|
||||
await cts.CancelAsync().ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
if (poller is not null)
|
||||
{
|
||||
await poller.WaitAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
|
||||
}
|
||||
}
|
||||
catch (Exception ex) when (ex is OperationCanceledException or TimeoutException)
|
||||
{
|
||||
// Stopping anyway.
|
||||
}
|
||||
finally
|
||||
{
|
||||
cts.Dispose();
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Asks Telegram who the token belongs to (<c>getMe</c>): proves the token before it is
|
||||
/// saved. Returns the bot's username; throws <see cref="InvalidOperationException"/>
|
||||
/// with Telegram's own description when the token is refused.
|
||||
/// </summary>
|
||||
public static async Task<string> GetMeAsync(string token, string baseUrl, HttpMessageHandler? handler, CancellationToken ct)
|
||||
{
|
||||
ArgumentException.ThrowIfNullOrWhiteSpace(token);
|
||||
using HttpClient client = handler is null ? new HttpClient() : new HttpClient(handler, disposeHandler: false);
|
||||
client.Timeout = TimeSpan.FromSeconds(20);
|
||||
using HttpResponseMessage response = await client.GetAsync($"{(string.IsNullOrWhiteSpace(baseUrl) ? "https://api.telegram.org" : baseUrl).TrimEnd('/')}/bot{token.Trim()}/getMe", ct).ConfigureAwait(false);
|
||||
string body = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
|
||||
if (!response.IsSuccessStatusCode)
|
||||
{
|
||||
throw new InvalidOperationException($"Telegram ha rifiutato il token (HTTP {(int)response.StatusCode}: {Describe(body)})");
|
||||
}
|
||||
|
||||
try
|
||||
{
|
||||
using JsonDocument doc = JsonDocument.Parse(body);
|
||||
if (doc.RootElement.TryGetProperty("result", out JsonElement result) && result.TryGetProperty("username", out JsonElement user) && user.GetString() is { Length: > 0 } name)
|
||||
{
|
||||
return name;
|
||||
}
|
||||
}
|
||||
catch (JsonException)
|
||||
{
|
||||
// Falls through to the error below.
|
||||
}
|
||||
|
||||
throw new InvalidOperationException($"risposta di getMe non riconosciuta: {Truncate(body)}");
|
||||
}
|
||||
|
||||
// -----------------------------------------------------------------------
|
||||
// Sending
|
||||
// -----------------------------------------------------------------------
|
||||
@@ -226,24 +342,25 @@ public sealed class TelegramNotifier : INotifier, IAsyncDisposable
|
||||
// Commands
|
||||
// -----------------------------------------------------------------------
|
||||
|
||||
private async Task PollLoopAsync()
|
||||
private async Task PollLoopAsync(CancellationToken ct)
|
||||
{
|
||||
while (!_cts.IsCancellationRequested)
|
||||
while (!ct.IsCancellationRequested)
|
||||
{
|
||||
try
|
||||
{
|
||||
await PollOnceAsync(_cts.Token).ConfigureAwait(false);
|
||||
await PollOnceAsync(ct).ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
catch (OperationCanceledException) when (ct.IsCancellationRequested)
|
||||
{
|
||||
return;
|
||||
}
|
||||
catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException or JsonException)
|
||||
{
|
||||
// A client timeout is a TaskCanceledException too: it is retried like a network error.
|
||||
_lastError = ex.Message;
|
||||
try
|
||||
{
|
||||
await Task.Delay(TimeSpan.FromSeconds(10), _cts.Token).ConfigureAwait(false);
|
||||
await Task.Delay(TimeSpan.FromSeconds(10), ct).ConfigureAwait(false);
|
||||
}
|
||||
catch (OperationCanceledException)
|
||||
{
|
||||
@@ -406,10 +523,11 @@ public sealed class TelegramNotifier : INotifier, IAsyncDisposable
|
||||
public async ValueTask DisposeAsync()
|
||||
{
|
||||
_queue.Writer.TryComplete();
|
||||
await StopCommandsAsync().ConfigureAwait(false);
|
||||
await _cts.CancelAsync().ConfigureAwait(false);
|
||||
try
|
||||
{
|
||||
await Task.WhenAll(_sender, _poller ?? Task.CompletedTask).WaitAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
|
||||
await _sender.WaitAsync(TimeSpan.FromSeconds(5)).ConfigureAwait(false);
|
||||
}
|
||||
catch (Exception ex) when (ex is OperationCanceledException or TimeoutException)
|
||||
{
|
||||
|
||||