# Dokładność obliczeń

## TL;DR

AstroWay API używa **Swiss Ephemeris** (oficjalnego kodu C od Astrodienst,
twórców astro.com) — tego samego silnika, na którym profesjonalni astrolodzy od
ponad 30 lat pracują w **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/m-c)
i Janus**. Zebraliśmy go w WebAssembly i udostępniliśmy przez warstwę REST API,
bez pośredniczącej marży. Każdy z podstawowych punktów końcowych obliczeniowych
jest pokryty testami regresyjnymi snapshot; dokładność silnika zweryfikowana przez
**triangulację** z trzema niezależnymi źródłami + przeciwko **NASA 5-Millennium
Eclipse Catalog**:

- **Pozycje planetarne**: `< 0.1 sekundy łuku` vs oficjalnego swetest CGI Astrodienst
- **Kuspy domów Placidusa**: `0.000"` idealne dopasowanie
- **Zaćmienia**: `< 1 minuta` vs NASA Eclipse Catalog
- **Linie ACG**: `< 1.5 km` na równiku vs swetest
- **Wschód/zachód Słońca**: `< 10 sekund` vs timeanddate.com
- **Księżyc VOC, wejścia, koniunkcje planetarne**: dokładność do ułamka sekundy

## Silnik

| Komponent | Wartość |
|-----------|---------|
| Biblioteka | Swiss Ephemeris C code (aloistr/swisseph) |
| Wersja | upstream Astrodienst C code |
| Bindings | swisseph-wasm (WebAssembly w Node.js) |
| Ephemeris | DE431 JPL ephemeris (przez pliki .se1) |
| Fallback | Analiza Moshiera (dla dat poza 1800–2399) |
| Współdzielenie kodu | Wspólny `@/core` z app.astroway.info — jeden silnik, dwa transporty |

## Metodyka

Dokładność jest weryfikowana przez **triangulację** — porównanie z trzema
niezależnymi źródłami:

### 1. swetest CGI (referencyjne)

Oficjalna implementacja referencyjna Swiss Ephemeris od samego Astrodienst —
komendy, które stworzyły **Astro.com** i obsługują miliony astrologów na całym
świecie. Najbardziej autorytatywne publiczne źródło. Nasz silnik jest
**identyczny** (0.00–0.07 sekundy łuku dryfu).

### 2. Kerykeion (Python)

Niezależna biblioteka Python używa `pyswisseph`-bindings zamiast naszego WASM.
Potwierdza, że nasza warstwa WASM nie zniekształca danych.

### 3. Prokerala API

Zdalne API Swiss Ephemeris (sidereal Lahiri). Systematyczny dryf 8–17 sekund
łuku związany z różnymi wersjami formuły Lahiri ayanamsa, a **nie** z
dokładnością silnika.

## Wyniki triangulacji

| Mapa | vs swetest (Astrodienst) | vs Kerykeion (Python) | vs Prokerala API |
|------|---------------------------|------------------------|------------------|
| Monroe 1926   | **0.00"** | 0.19" | 16.95" (systematyczny) |
| Diana 1961    | **0.00"** | 0.69" | 8.18" (systematyczny)  |
| Einstein 1879 | 0.07"     | Artefakt LMT Kerykeion | 14.96" (systematyczny) |

## Zestaw regresyjny na poziomie endpointów

Każdy z podstawowych punktów końcowych obliczeniowych jest pokryty zamrożonymi
testami snapshot na 3 mapach referencyjnych (Monroe / Diana / Einstein) =
**{siteMeta.snapshotCount} snapshotów**.

Pakiet snapshot wykrywa:

- **Błędy mapowania danych wejściowych** — nieprawidłowy id planety, UT, system domów
- **Obróbkę końcową** — zaokrąglanie, konwersja jednostek, utrata znaku
- **Rozbieżność domyślnych ustawień** — węzeł średni vs rzeczywisty, geocentryczny vs topocentryczny
- **Dryft schematu** — walidacja pominęła nieprawidłowy kształt
- **Nieaktualny deploy** — dystrybucja prod nie odpowiada kodowi

Tolerancja: `5e-5°` (≈0.18 sekundy łuku) domyślnie dla wszystkich pól numerycznych.

## Szczegółowe benchmarki

### Pozycje planetarne (tropik, vs swetest)

| Mapa | Data | Maksymalny dryft |
|------|------|------------------|
| Marilyn Monroe  | 1926-06-01 | **0.00"** |
| Princess Diana  | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07"     |

### Kuspy domów Placidusa (vs swetest)

| Mapa | dryft ASC | dryft MC | Maksymalny dryft kuspy |
|------|-----------|----------|------------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana  | 0.000" | 0.000" | 0.000" |

### Zaćmienia (vs NASA 5-Millennium Catalog)

| Wydarzenie | Maksymalny NASA | Nasz maksymalny | Dryft |
|------------|-----------------|-----------------|-------|
| 2025-03-14 Zaćmienie Księżyca całkowite  | 06:58 UT | 06:58 UT | 0.8 min |
| 2025-03-29 Zaćmienie Słońca częściowe | 10:47 UT | 10:47 UT | 0.5 min |
| 2025-09-07 Zaćmienie Księżyca całkowite  | 18:11 UT | 18:11 UT | 0.8 min |
| 2025-09-21 Zaćmienie Słońca częściowe | 19:41 UT | 19:42 UT | 1.0 min |

### Astrokartografia (vs formuły RA ze swetest)

Wszystkie linie MC/IC/ASC/DSC używają poprawnej formuły `longitude = RA − GMST`
(standard Kenneth Bowser). Dryft względem wzorca: **< 1.5 km** na równiku dla
wszystkich planet.

### Wschód / Zachód Słońca (vs timeanddate.com)

| Lokalizacja | Data | Parametr | Dryft |
|-------------|------|----------|-------|
| Londyn | 2026-04-15 | Wschód Słońca | 0.6 s |
| Londyn | 2026-04-15 | Zachód Słońca  | 9 s   |

**Lokalizacje polarne** (|szer. geogr.| > 66.5°) automatycznie zwracają `polarState` +
ostrzeżenie, że zwyczajne godziny planetarne nie są zdefiniowane.

### Orbisy aspektów

AstroWay używa **zmiennych orbisów** per-planeta (reguła MIN dwóch planet),
jak w ZET9 i astro.com. Orbisy domyślne (dla mapy natalnej):

| Aspekt | Słońce | Księżyc | Planety wewnętrzne | Jowisz | Planety zewnętrzne |
|--------|--------|---------|--------------------|--------|-------------------|
| Koniunkcja | 12°  | 10° | 5° | 8° | 5° |
| Sekstyl     | 6.5° | 6°  | 5° | 5° | 5° |
| Kwadratura  | 10°  | 8°  | 5° | 7° | 5° |
| Trygon      | 12°  | 8°  | 5° | 5° | 5° |
| Opozycja    | 12°  | 10° | 5° | 8° | 5° |

Mniejsze aspekty (36°, 40°, 45°, 72°, 108°, 135°, 144°) **domyślnie
wyłączone**. Włączane są jawnie przez `ALL_ASPECTS`.

## Szerokości polarne

Dla |szer. geogr.| > 66.5° systemy Placidusa / Koch / Regiomontanusa są
matematycznie niezdefiniowane. W takich przypadkach Swiss Ephemeris
automatycznie zwraca Porphyry, a nasze API dodaje ostrzeżenie:

```json
{
  "system": "P",
  "warning": "System Placidus nie jest zdefiniowany dla szerokości=68.96° (> 66.5°). Swiss Ephemeris użył Porphyry..."
}
```

## Ciągła weryfikacja

Regresja jest sprawdzana **przy każdym PR** przez CI:

- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshotów przeciwko mapom referencyjnym (Monroe / Diana / Einstein) + synastria / kompozyt / Davison
- `.github/workflows/api-accuracy.yml` — automatyczne uruchamianie przy PR
- Triangulacja przeciwko swetest CGI + Kerykeion — co tydzień
- Monitorowanie upstream Swiss Ephemeris przez Dependabot

## Znane ograniczenia

- **Daty poza zakresem** (przed 1800 i po 2399): używana jest analiza Moshiera,
  dokładność ~0.1" (vs < 0.01" dla SWIEPH z plikami DE431)
- **Prawdziwy Lilith (id=13) vs średni Lilith (id=12)**: różnica do 12° — domyślnie
  średni Lilith (stabilne zachowanie), prawdziwy Lilith dostępny przez
  `planetIds: [13]`
- **Topocentryczny vs geocentryczny**: domyślnie geocentryczny

## Linki

- Swiss Ephemeris: https://www.astro.com/swisseph/
- swetest CGI: https://www.astro.com/swisseph/swetest.htm
- Katalog zaćmień NASA: https://eclipse.gsfc.nasa.gov/
- Kerykeion: https://github.com/g-battaglia/kerykeion
- Astrodienst: https://www.astro.com/

## Kontakt

W sprawach dotyczących dokładności: pisz na support@astroway.info z danymi mapy
i oczekiwanym wzorcem (astro.com lub inne autorytatywne źródło).