spec: cosa ha scoperto la costruzione del motore

2026-08-22 11:02:26 +02:00
parent 42a039ae6b
commit 0e9b081a79
1 changed files with 54 additions and 0 deletions
@@ -384,6 +384,60 @@ capita.
   confermata. L'HRV entra nel motore come passthrough, quindi senza quel canale
   va inserito a mano.
 ## 12-bis. Cosa ha scoperto la costruzione del motore (22/08)
 Il motore è stato costruito il 22/08 (ramo `feat/longevity`, 6 task, 308 test). Il porting
 è fedele: eseguendo la funzione dimostrativa del cliente sui due motori, i sette assi, i tre
 macro-score e la Fitness Age **combaciano numero per numero**.
 ### Due divergenze deliberate dall'oracolo, entrambe volute
 1. **Un punteggio insufficiente non espone un valore.** Nell'originale la funzione di
   aggregazione restituisce il numero anche quando dichiara l'elemento insufficiente; qui il
   tipo non ha proprio il campo. È ciò che rende impossibile mostrare un numero dove i dati
   non bastano.
 2. **La Fitness Age esclude gli assi insufficienti**, mentre l'oracolo li include comunque.
   ⚠️ **Cambia il numero, e parecchio**: sullo stesso profilo parziale, 25,0 contro 34,8 —
   quasi dieci anni. Chi confrontasse il nostro referto con il Python del cliente su un
   profilo incompleto concluderebbe che il porting è rotto. **Da dire a Nicola.**
 ### ⚠️ Le curve dei test fisici non sono collegate, e agganciarle non sarà «solo dati»
 Le venti curve dei test misurati sono portate e verificate, ma **irraggiungibili dal
 motore**: il vocabolario delle curve del registro non ha nomi per loro, e la funzione che
 applica una curva non può ricevere età e sesso, che quasi tutte richiedono.
 📌 Questo contraddice la §5, dove il registro è presentato come dato che si estende senza
 toccare il codice. **È vero per il questionario, non per i test fisici**: agganciarli
 richiede di estendere il vocabolario e la firma. Il piano degli import deve saperlo, perché
 oggi crede di trovare la presa già montata.
 ### Il confine dove la barriera finisce
 Il tipo protegge il codice; la tabella `score` ha ora anche un vincolo che rifiuta un valore
 scritto sotto uno stato che lo nega. ⚠️ Ma quel vincolo entra solo nei database **creati da
 qui in avanti**: lo schema gira con `CREATE TABLE IF NOT EXISTS`, che su un file esistente
 non fa nulla. Oggi nessun database esiste ancora — diventa un problema il giorno del primo
 deploy, ed è quello il momento di ricordarsene.
 ### La storia dei punteggi si tiene
 Un ricalcolo **aggiunge** righe invece di sovrascriverle, coerentemente col congelamento del
 §6: sovrascrivere cancellerebbe proprio ciò che il congelamento protegge. La lettura passa da
 una funzione tipata che restituisce l'ultimo calcolo per sessione — la dashboard non deve
 inventarsi una query sua.
 ### 🔲 Una domanda per Nicola, sulla voce più pesante del modello
 `hrv` pesa **0,50 su due assi** — *Recupero* ed *Energia* — ed è la singola voce più pesante
 di tutto il modello. Nel motore è un dato solo, condiviso. Ma nella funzione dimostrativa
 dell'oracolo i due assi ricevono **numeri diversi sotto lo stesso nome** (68 e 65).
 O è la stessa misura riusata su due assi — come il plank, che Nicola ha già confermato — e i
 due numeri sono illustrativi; oppure sono due metriche distinte, e allora le stiamo fondendo
 per sbaglio. Diventa concreto appena si collega Stress Index, che è la sorgente di quel dato.
 ---
 ## 12. Cosa l'implementazione ha scoperto — da chiudere prima del motore
 Lo strato dati è stato costruito il 21/08 (ramo `feat/longevity`, 19 commit, 241 test).