Cerbero-Bite/docs/06-operational-flow.md

# 06 — Flussi operativi

Tre flussi principali, tutti orchestrati dallo scheduler interno
APScheduler.

## Flusso 1 — Avvio engine

```
1. Carica strategy.yaml + strategy.local.yaml (override)
2. Validazione schema (pydantic) — fail veloce
3. Acquisisci lock file (data/.lockfile)
4. Apri SQLite, esegui migrations
5. Health check MCP server (versioni + ping)
6. Riconciliatore stato:
     a. legge positions con status in {awaiting_fill, open, closing}
     b. per ognuna chiama cerbero-memory.is_acknowledged + Deribit get_positions
     c. allinea SQLite alla realtà del broker (sempre la realtà vince)
     d. log delle discrepanze come WARNING
7. Health check sistema OK?  →  arma scheduler
                     KO?     →  kill switch + alert + idle
8. Log ENGINE_START
```

L'avvio è progettato per essere **safe**: se qualcosa non torna, il
sistema si rifiuta di operare. Mai partire con uno stato dubbio.

## Flusso 2 — Settimanale (entry)

Trigger: cron `0 14 * * MON` (lunedì 14:00 UTC).

```
START
 ├── safety.system_healthy()?               → no  → log + skip
 ├── state.has_open_position()?             → yes → log + skip
 ├── snapshot dati di mercato (parallel):
 │     spot, dvol, funding_perp, funding_cross, macro_calendar,
 │     holdings_pct, capital
 ├── entry_validator.validate_entry         → fail → log ENTRY_REJECTED + reasons
 ├── entry_validator.compute_bias           → None → log ENTRY_REJECTED ("no_bias")
 ├── deribit.get_options_chain (DTE 14-21)
 ├── combo_builder.select_strikes           → None → log ENTRY_REJECTED ("no_strike")
 ├── deribit.get_orderbook per le 2 gambe
 ├── liquidity_gate.check                   → fail → log ENTRY_REJECTED ("illiquid")
 ├── sizing_engine.compute_contracts        → 0    → log ENTRY_REJECTED ("undersize")
 ├── combo_builder.build → ComboProposal
 ├── greeks_aggregator.aggregate
 ├── reporting.pre_trade(proposal) → testo Telegram
 ├── telegram.request_confirmation(timeout=60min)
 │     ├── confermato:
 │     │     ├── state.create_position (status="proposed")
 │     │     ├── memory.push_user_instruction
 │     │     ├── state.update(status="awaiting_fill")
 │     │     └── log ENTRY_CONFIRMED
 │     ├── rifiutato:
 │     │     └── log ENTRY_REJECTED_BY_USER
 │     └── timeout:
 │           └── log ENTRY_TIMEOUT
 └── END
```

### Tempo previsto end-to-end

- Snapshot dati: 3-5 secondi
- Algoritmi puri: < 0.5 secondi
- Conferma utente: variabile (max 60 min)

Il critical path automatico è **sotto 10 secondi**. La latenza umana
non rallenta i prezzi: se Adriano risponde dopo 30 minuti, l'engine
prima di inviare l'istruzione **rivaluta** spot, mid e dvol e abortisce
l'apertura se le condizioni sono cambiate (slippage > 8% o dvol fuori
banda o macro nuova).

## Flusso 3 — Monitoring (12h)

Trigger: cron `0 2,14 * * *` (02:00 e 14:00 UTC, ogni giorno).

```
START
 ├── safety.system_healthy()? → no  → kill switch (no auto-close ciechi)
 ├── per ogni position con status="open":
 │     ├── snapshot:
 │     │     spot, dvol, mark_combo, delta_short, return_4h
 │     ├── exit_decision.evaluate
 │     ├── action == HOLD:
 │     │     └── log EXIT_EVALUATED("hold")
 │     ├── action == CLOSE_*:
 │     │     ├── reporting.exit_proposal(position, decision)
 │     │     ├── telegram.request_confirmation(timeout=30min)
 │     │     │     ├── confermato:
 │     │     │     │     ├── memory.push_user_instruction (close)
 │     │     │     │     ├── state.update(status="closing")
 │     │     │     │     └── log EXIT_CONFIRMED
 │     │     │     ├── rifiutato:
 │     │     │     │     └── log EXIT_DEFERRED (resterà in HOLD fino a prossimo ciclo)
 │     │     │     └── timeout:
 │     │     │           └── escalation: per CLOSE_STOP/CLOSE_VOL/CLOSE_DELTA
 │     │     │                 → invia comunque l'istruzione (urgenza prevale)
 │     │     │                 per altri motivi → log EXIT_TIMEOUT, attende prossimo ciclo
 │     └── continue
 └── END
```

### Politica di escalation

I trigger di uscita non sono uguali. Alcuni hanno **urgenza alta** che
giustifica l'esecuzione anche senza conferma utente entro la finestra:

| Trigger | Urgenza | Comportamento su timeout |
|---|---|---|
| `CLOSE_PROFIT` | Bassa | Attendi prossimo ciclo (può migliorare) |
| `CLOSE_STOP` | **Alta** | Esegui chiusura senza conferma esplicita |
| `CLOSE_VOL` | **Alta** | Esegui chiusura senza conferma |
| `CLOSE_DELTA` | **Alta** | Esegui chiusura senza conferma |
| `CLOSE_TIME` | Media | Attendi 1 ciclo extra; al secondo timeout esegui |
| `CLOSE_AVERSE` | Media | Attendi prossimo ciclo |

Su escalation hard, Telegram riceve un messaggio **post-fact**: "ho
chiuso la posizione X per stop loss perché non ho ricevuto risposta in
30 min e l'urgenza non consentiva attesa".

## Flusso 4 — Mensile (Kelly recalibration)

Trigger: cron `0 12 1 * *` (primo di ogni mese alle 12:00 UTC).

```
1. Carica trades chiusi negli ultimi 365 giorni
2. kelly_recalibration.recalibrate
3. Genera report mensile:
     - performance vs simulazione MC
     - win rate, avg win/loss, edge
     - kelly suggerito vs corrente
     - violazioni regole (deve essere 0)
4. telegram.send (informativo, no conferma)
5. brain_bridge.write_note(
     path="strategies/cerberus-bite/monthly-report-YYYY-MM.md",
     content=report
   )
6. log KELLY_RECALIBRATED
```

L'aggiornamento di `strategy.yaml` resta **manuale**: Adriano legge il
report, discute con Milito, e committa il nuovo file di config (con
giustificazione nel commit message). Nessun auto-update.

## Flusso 5 — Health check periodico

Trigger: ogni 5 minuti.

```
1. ping ogni MCP usato → ms latency
2. SQLite read-write probe (transazione fittizia)
3. lock file ancora valido
4. ultima fill di Cerbero core ricevuta entro tempo atteso
5. state.system_state.kill_switch == 0
Se qualsiasi passo fallisce:
  - log HEALTH_DEGRADED
  - se 3 fallimenti consecutivi → kill_switch + alert
  - se 5 fallimenti consecutivi → restart automatico (1 sola volta al giorno)
```

## Flusso 6 — Recovery dopo crash

Quando l'engine riparte:

1. Riapre SQLite + log della giornata.
2. Per ogni posizione `awaiting_fill`:
   - Chiede a `cerbero-memory.get_status(instruction_id)`
   - Se filled → aggiorna a `open`
   - Se cancelled → aggiorna a `cancelled`
   - Se ancora pending → mantiene stato e riprende il monitoraggio
3. Per ogni posizione `closing`:
   - Stessa logica
4. Per ogni posizione `open`:
   - Verifica che esista realmente sul broker (Deribit `get_positions`)
   - Se non esiste → flag `state_inconsistent` + alert + kill switch
5. Riconciliazione completata → ENGINE_START.

Il sistema **mai** prende decisioni di trading durante recovery: solo
allinea lo stato. Il primo decision loop avviene al prossimo trigger
naturale.

## Diagramma di stato di una posizione

```
                        ┌─ rejected_by_user ──→ cancelled
                        │
         (entry)        ├─ timeout ──────────→ cancelled
proposed ─────────────► │
                        ├─ confirmed
                        ▼
                  awaiting_fill
                        │
                        ├─ no_fill ──────────→ cancelled
                        ├─ filled ───────────► open
                        │                       │
                        │           (exit_decision != HOLD)
                        │                       │
                        │                       ▼
                        │                    closing
                        │                       │
                        │                       ├─ no_fill (escalated) → manual_intervention
                        │                       └─ filled ──────────→ closed
```

## Cron summary

| Cron | Trigger | Frequenza |
|---|---|---|
| `0 14 * * MON` | Entry evaluation | Settimanale |
| `0 2,14 * * *` | Position monitoring | 2× giorno |
| `0 12 1 * *` | Kelly recalibration | Mensile |
| `*/5 * * * *` | Health check | 5 min |
| `0 0 * * *` | Backup SQLite + rotation log | Giornaliero |
| `0 8 * * *` | Daily digest Telegram | Giornaliero |

Tutti gli orari in UTC.