Worker Data Passthrough Pattern

0011-worker-data-passthrough

Data: 2025-12-06 Stato: Accettato Contesto: Bug “bgcolor flow interruption” (v5.1.0)

Il Contesto

Durante l’implementazione della feature strategy.bgcolor(), abbiamo riscontrato un bug critico in cui i dati prodotti dal BacktestEngine non raggiungevano la UI. La causa è stata identificata nel BacktestWorker: questo componente ricostruiva manualmente il dizionario dei risultati (Approccio “Whitelist”), scartando involontariamente qualsiasi chiave non esplicitamente prevista nel suo codice (in questo caso, background_events).

La Decisione

Adottiamo ufficialmente il Pattern “Passthrough” (Merge) per tutti i Worker e gli Handler intermedi che trasportano dati complessi.

Invece di costruire un nuovo dizionario selezionando le chiavi:

# ❌ ANTI-PATTERN (Vietato)
return {
    "stats": engine_output["stats"],
    "trades": engine_output["trades"]
    # Se engine_output ha nuove chiavi, vengono perse!
}

I Worker DEVONO copiare l’output originale e aggiornarlo/arricchirlo:

# ✅ PASSTHROUGH PATTERN (Obbligatorio)
results = engine_output.copy()
results.update({
    "metrics": calculated_metrics,
    "equity": calculated_equity
})
return results

Conseguenze

Positive

• Estensibilità: Aggiungere nuovi dati all’Engine non richiede più la modifica a catena di Worker e Handler.
• Robustezza: Si evitano bug silenziosi di perdita dati.

Negative

• Payload Size: Potremmo trasportare dati “inutili” se l’Engine produce molto output di debug, ma il trade-off è accettabile.