# Evidence workflow

## Indice

1. Contratto del benchmark
2. Metriche e budget
3. Matrice di diagnosi
4. Piano a wave
5. Acceptance e soak
6. Reporting

## 1. Contratto del benchmark

Registra prima della misura:

- URL/flow e prerequisiti di autenticazione;
- build/commit e modalità Debug/Release;
- browser/versione e strumento di controllo;
- dataset e stato cold/warm;
- viewport, zoom, CPU e network throttling;
- azione esatta e criterio di completamento;
- numero di campioni e trattamento degli outlier.

Usa gli ID del dataset solo nella configurazione del benchmark. Non usarli per abilitare fix nella produzione.

## 2. Metriche e budget

### Interazioni

Per click, checkbox, tab e pannelli:

- misura input-to-next-paint o una milestone DOM/applicativa;
- separa il primo utilizzo dalle ripetizioni;
- segnala se l'azione include rete;
- riporta p50, p95 e worst quando ci sono campioni sufficienti.

Non equiparare il tempo impiegato dal driver di automazione al tempo del main thread. Se possibile, inserisci marker nella pagina con `performance.mark()` e misura dalla pagina stessa.

### Caricamento

Raccogli:

- TBT o somma delle porzioni dei long task oltre 50 ms;
- numero e durata massima dei long task;
- richieste, byte trasferiti e duplicati non serviti da cache;
- readiness funzionale e strutturale;
- layout shift o geometrie instabili se pertinenti.

### Memoria e lifecycle

Confronta baseline e post-soak:

- heap usato dopo GC, se disponibile;
- document/node count;
- event listener per owner o almeno totale;
- observer, timer, RAF, interop reference e controller vivi;
- richieste ancora in-flight dopo navigation/disposal.

Una crescita momentanea non prova un leak. Richiedi più cicli e verifica che il valore non torni al plateau.

## 3. Matrice di diagnosi

| Segnale | Ipotesi prioritarie | Evidenza da raccogliere |
|---|---|---|
| Long task JS | loop, serializzazione, callback duplicate | bottom-up/call tree, conteggio invocazioni |
| Style/layout alto | read/write interleaved, misura di troppe celle | invalidation reason, geometry read/write counters |
| Render managed ripetuto | stato propagato troppo in alto, `StateHasChanged` ridondante | render generation per componente |
| Network duplicato | cache assente, richieste concorrenti uguali | initiator, key, timing, cache status |
| UI applica dati vecchi | race tra richieste | generation/request id, ordine start/end/apply |
| Heap/nodi crescono | listener/observer/interop non disposti | owner count dopo mount/unmount |
| Primo uso lento, warm veloce | mount e inizializzazione legittimi o ricreazione evitabile | cold/warm DOM e render delta |
| Ogni riapertura lenta | subtree distrutto e ricreato | node identity e lifecycle events |
| Scroll lento | structural work durante scroll, listener globali | callback/frame e pass strutturali |
| Funzione WASM opaca | rendering managed o serializzazione | profilo con simboli solo se materialmente dominante |

## 4. Piano a wave

Adotta wave con exit gate:

1. **Baseline/observability**: benchmark ripetibile e diagnostica opt-in.
2. **Fix certi**: cancellation, supersession, coalescing, ownership e richieste duplicate.
3. **Rendering/DOM**: riduci pass strutturali solo con misure prima/dopo.
4. **Interventi condizionali**: component extraction, cache o virtualizzazione solo se il budget resta superato.
5. **Acceptance/consolidamento**: regressioni, soak, rimozione di esperimenti e documentazione.

Termina ogni wave runtime con rebuild/deploy dell'owner quando l'ambiente non è compilabile autonomamente.

## 5. Acceptance e soak

### Suite rapida

- load cold/warm;
- interazione singola e sequenza di toggle;
- apertura/chiusura cold e warm;
- dettaglio pieno, vuoto ed errore;
- scroll orizzontale/verticale, sorting e grouping se toccati;
- componenti visibili/nascosti;
- console, network e readiness.

### Suite lunga

- 20 o più navigation/mount/unmount con confronto post-GC;
- reload ripetuti con CPU throttling;
- campionamento geometria durante il primo load se esistono glitch intermittenti;
- resize/move/lock per layout manager;
- navigation durante request, debounce o drag;
- due tab e cross-tab quando il change set tocca bus o drag globali.

Riduci il volume solo dichiarando il rischio residuo. Non trasformare una suite rapida in prova di assenza leak.

## 6. Reporting

Usa questa forma per ogni finding:

```text
Fatto osservato: ...
Evidenza: trace/log/DOM/file/commit ...
Inferenza: ...
Confidenza: alta/media/bassa
Azione: ...
Exit gate: ...
```

Registra anche decisioni “non necessario”: metrica, soglia e motivo per cui il refactor non è giustificato.