docs: piano del motore di calcolo, verificato contro l'oracolo del cliente

2026-08-22 08:27:51 +02:00
parent 59b453c67e
commit bc9d31e193
3 changed files with 1419 additions and 0 deletions
@@ -0,0 +1,22 @@
+# L'oracolo del motore di calcolo
+
+`isl_scoring_engine.py` è il motore di punteggio **scritto dal cliente** (In-Sanity Lab),
+ricevuto il 2026-08-21. Non è codice nostro e non va modificato: sta qui perché è
+l'**oracolo** contro cui verifichiamo il porting in TypeScript.
+
+Il porting delle curve è la parte più delicata della piattaforma: un coefficiente
+trascritto male produce un punteggio sanitario sbagliato che sembra plausibile e che
+nessun test funzionale intercetterebbe, perché diventerebbe il valore "atteso" di tutto
+ciò che viene dopo. La fedeltà non è garantita dalla trascrizione, ma dal confronto
+numerico: `genera-riferimento.py` esegue questo motore su una griglia di casi e scrive
+`riferimento.json`, che il test TypeScript rilegge per confrontare i due risultati.
+
+Serve `python3` (solo libreria standard: il motore importa unicamente `dataclasses` e
+`typing`).
+
+## Rigenerare il riferimento
+
+    python3 tests/longevity/riferimento/genera-riferimento.py
+
+Va rifatto solo se il cliente manda una versione nuova del motore. In quel caso il
+confronto dirà da sé quali curve sono cambiate.