Como mantemos a precisão sob controle: CI versus swetest e NASA

Precisão é o que o usuário silenciosamente verifica você em Astrodienst. Se a carta nativa se desfaz em uma hora angular, a reclamação chegará rapidamente. E o pior nesse caso é que a precisão pode ser facilmente quebrada de forma imperceptível: um refatoring no código de efeitos, e metade dos endpoints silenciosamente desaparece para segundos de arco.

Aqui é como não deixamos isso acontecer.

As posições planetárias são calculadas pelo Swiss Ephemeris, compilado em WASM. Chave: é a mesma base e no navegador do nosso aplicativo e no servidor da API. Uma base de código core/, vinculada ao backend através de um alias de repositório cruzado e embutida no pacote no build. Não há “implementação do navegador” e “implementação do servidor” que possam divergir - divergir de nada.

Para datas fora do domínio principal de efeitos, há um fallback analítico (Moshier), um pouco mais bruto, mas sem lacunas nos limites. Honesto: não declaramos publicamente a versão real do motor, pois a versão real do kernel é inferior à mais recente upstream, e escrever uma grande cifra seria uma mentira.

Cada endpoint de cálculo tem um conjunto de snapshots congelados - 873 JSON-fixtures no momento desse build. O runner executa o endpoint em cartas de referência e verifica com a fixação. Qualquer desvio da longitude planetária maior do que 5e-5° (0,18”) faz o teste falhar.

As cartas de referência foram selecionadas para bater nos limites, e não apenas no “centro conveniente”:

• Monroe, Diana, Einstein, Bowie - cartas históricas com dados de nascimento conhecidos
• polar latitude - onde os sistemas de casa são gerados
• ecuatorial - onde eles se comportam de forma diferente
• southern hemisphere - verificação da simetria

Os casos de limite capturam exatamente as regresses que não são visíveis na carta do cidadão comum.

Snapshots capturam regresses em relação a si mesmas. Para verificar a verdade absoluta, cada lançamento é comparado com fontes independentes:

Desvios com Prokerala - não é um erro: é uma implementação diferente da fórmula Lahiri, e documentamos isso explicitamente, e não o escondemos. Com swetest, que é o padrão da indústria, o desvio é zero.

As linhas astronômicas são verificadas geometricamente separadamente - a precisão no equador é melhor do que 1,5 km.

A precisão é CI-gate, e não uma verificação única:

• api-accuracy.yml - em cada PR, o backend-execução executa o conjunto completo de snapshots + triângulo. O teste vermelho bloqueia a fusão.
• check-eclipse-accuracy.yml - uma vez por ano, compara eclipses com o catálogo da NASA; desvios acima do limiar automaticamente abrem um problema.
• check-sweph-updates.yml - uma vez por semana, verifica o upstream Swiss Ephemeris e o pacote WASM; uma nova versão - problema na revisão, sem autómergio (atualização do motor de efeitos - muito sensível para autoupdate).

Garantia simples: posições planetárias dentro de < 0.1 segundos de arco do Swiss Ephemeris padrão, e essa margem é protegida automaticamente, e não é uma promessa no README. Se alguma vez surgir uma regressão, ela cairá no nosso CI, e não na reclamação do seu usuário.

A versão pública dessas cifras, com a tabela de desvios para cartas específicas, vive na página Precisão.