Come teniamo sotto controllo la precisione: CI contro swetest e NASA

La precisione è ciò su cui l’utente ti verifica in silenzio su Astrodienst. Se un tema natale si discosta di un primo d’arco, il reclamo arriva in fretta. E la cosa peggiore è che la precisione si rompe facilmente senza che nessuno se ne accorga: un refactoring nel codice delle effemeridi e metà degli endpoint slittano silenziosamente di qualche secondo d’arco.

Ecco come impediamo che succeda.

Le posizioni planetarie sono calcolate da Swiss Ephemeris. Il punto chiave: la nostra app e l’API condividono lo stesso motore di calcolo, una sola codebase. Non esistono due implementazioni che possano divergere, quindi non c’è nulla che possa divergere.

Per le date fuori dall’intervallo principale delle effemeridi c’è un fallback analitico (Moshier), un po’ meno preciso, ma senza discontinuità ai bordi. Una scelta di onestà consapevole: non dichiariamo pubblicamente la versione specifica del motore, perché la versione reale del nucleo è precedente all’ultima upstream, e scrivere un numero altisonante sarebbe una bugia.

Ogni endpoint di calcolo ha un insieme di snapshot congelati: 888 fixture JSON al momento di questa build. Il runner esegue l’endpoint sui temi di riferimento e lo confronta byte per byte (entro una tolleranza) con la fixture. Qualsiasi scostamento della longitudine planetaria superiore a 5e-5° (0.18″) fa fallire il test.

I temi di riferimento sono scelti per colpire i casi limite, non solo il centro “comodo”:

• Monroe, Diana, Einstein, Bowie: temi storici con dati di nascita noti
• latitudine polare: dove i sistemi di case degenerano
• equatoriale: dove si comportano diversamente
• emisfero australe: verifica della specularità

Sono proprio i casi limite a scovare le regressioni che non si vedono sul tema di un ipotetico abitante di Kyiv.

Gli snapshot intercettano le regressioni rispetto a se stessi. Per verificare la verità assoluta, ogni release viene confrontata con fonti indipendenti:

Lo scostamento da Prokerala non è un errore: sono implementazioni diverse della formula Lahiri, e lo documentiamo esplicitamente invece di nasconderlo. Con swetest, che è lo standard di riferimento del settore, la deriva è zero.

Le linee astrocartografiche vengono verificate a parte in modo geometrico: all’equatore la precisione è migliore di 1.5 km.

La precisione è un gate di CI, non una verifica una tantum:

• api-accuracy.yml: a ogni PR sul codice backend esegue l’intero set di snapshot + la triangolazione. Un test rosso blocca il merge.
• check-eclipse-accuracy.yml: una volta all’anno confronta le eclissi con il catalogo NASA; uno scostamento oltre la soglia apre automaticamente una issue.
• check-sweph-updates.yml: ogni settimana tiene d’occhio l’upstream di Swiss Ephemeris; una nuova versione genera una issue da revisionare, senza merge automatico (aggiornare il motore delle effemeridi è troppo delicato per un aggiornamento automatico).

La garanzia è semplice: posizioni planetarie entro < 0.1 secondi d’arco dallo Swiss Ephemeris di riferimento, e questo limite è protetto dall’automazione, non da una promessa nel README. Se un giorno comparirà una regressione, fallirà nella nostra CI, non in un reclamo del tuo utente.

La versione pubblica di questi numeri, con una tabella degli scostamenti su temi specifici, si trova nella pagina Precisione.