# Precizia calculelor

## TL;DR

API-ul AstroWay folosește **Swiss Ephemeris** (codul C oficial de la Astrodienst,
creatorii lui **astro.com**) — același motor pe care astrologii profesioniști l-au
folosit timp de 30+ ani în **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/lună)
și Janus**. L-am compilat în WebAssembly și l-am expus printr-un strat REST, fără
margini de intermediere. Fiecare dintre endpoint-urile de bază de calcul este
acoperit de teste snapshot de regresie; precizia motorului a fost verificată prin
**triangulație** cu trei surse independente + comparativ cu **NASA 5-Millennium
Eclipse Catalog**:

- **Poziții planetare**: `< 0.1 arcsec` față de swetest CGI oficial Astrodienst
- **Cuspidale caselor Placidus**: `0.000"` potrivire exactă
- **Eclipse**: `< 1 minut` față de NASA Eclipse Catalog
- **Linii ACG**: `< 1.5 km` la ecuator față de swetest
- **Răsărit/apus de Soare**: `< 10 secunde` față de timeanddate.com
- **VOC Lună, ingresse, conjuncții planetare**: precizie la fracțiuni de secundă

## Motorul

| Componentă | Valoare |
|------------|---------|
| Bibliotecă | Codul C Swiss Ephemeris (aloistr/swisseph) |
| Versiune | codul C upstream Astrodienst |
| Bindings | swisseph-wasm (WebAssembly în Node.js) |
| Ephemeris | DE431 JPL ephemeris (prin fișiere .se1) |
| Fallback | Moshier analitic (pentru date în afara intervalului 1800-2399) |
| Partajare cod | Partajat `@/core` cu app.astroway.info — un singur motor, două transporturi |

## Metodologie

Precizia este verificată prin **triangulație** — compararea cu trei surse
independente:

### 1. swetest CGI (etalon)

Implementarea de referință oficială Swiss Ephemeris de la chiar Astrodienst —
comenzile care au creat **Astro.com** și deservește milioane de astrologi din
întreaga lume. Cea mai autoritară sursă publică. Motorul nostru este **identic**
(0.00–0.07 secunde de arc de drift).

### 2. Kerykeion (Python)

O bibliotecă independentă Python care folosește bind-urile `pyswisseph` în locul
stratului nostru WASM. Confirmă că stratul nostru WASM nu distorsionează datele.

### 3. Prokerala API

Un API Swiss Ephemeris la distanță (ayanamsa Lahiri sideral). Drift-ul sistematic
de 8–17 secunde de arc este legat de diferite versiuni ale formulei Lahiri
ayanamsa, și **nu** de precizia motorului.

## Rezultate ale triangulației

| Hartă | față de swetest (Astrodienst) | față de Kerykeion (Python) | față de Prokerala API |
|-------|-------------------------------|----------------------------|-----------------------|
| Monroe 1926   | **0.00"** | 0.19" | 16.95" (sistematic) |
| Diana 1961    | **0.00"** | 0.69" | 8.18" (sistematic)  |
| Einstein 1879 | 0.07"     | artefact LMT Kerykeion | 14.96" (sistematic) |

## Set de regresie la nivel de endpoint

Fiecare dintre endpoint-urile de bază de calcul este acoperit de teste snapshot
înghețate pe 3 hărți de referință (Monroe / Diana / Einstein) = **{siteMeta.snapshotCount}
snapshots**.

Suita de snapshots detectează:

- **Bug-uri de mapare a datelor de intrare** — id incorect al planetei, UT, sistem de case
- **Post-procesare** — rotunjire, conversie de unități, pierderea semnului
- **Divergență de valori implicite** — nodul mediu vs. adevărat, geocentric vs. topocentric
- **Drift de schemă** — validarea a ratat o formă incorectă
- **Depuneri învechite** — dist-ul de producție nu corespunde codului

Toleranță: `5e-5°` (≈0.18 secunde de arc) implicit pentru toate câmpurile numerice.

## Benchmarks detaliate

### Poziții planetare (tropic, față de swetest)

| Hartă | Dată | Drift maxim |
|-------|------|-------------|
| Marilyn Monroe  | 1926-06-01 | **0.00"** |
| Princess Diana  | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07"     |

### Cuspidale caselor Placidus (față de swetest)

| Hartă | drift ASC | drift MC | Drift maxim al cuspidalei |
|-------|-----------|----------|----------------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana  | 0.000" | 0.000" | 0.000" |

### Eclipse (față de NASA 5-Millennium Catalog)

| Eveniment | Maxim NASA | Maximul nostru | Drift |
|-----------|------------|----------------|-------|
| 2025-03-14 Lunară Totală  | 06:58 UT | 06:58 UT | 0.8 min |
| 2025-03-29 Parțială Solară | 10:47 UT | 10:47 UT | 0.5 min |
| 2025-09-07 Lunară Totală  | 18:11 UT | 18:11 UT | 0.8 min |
| 2025-09-21 Parțială Solară | 19:41 UT | 19:42 UT | 1.0 min |

### Astrocartografie (față de formula RA din swetest)

Toate liniile MC/IC/ASC/DSC folosesc formula corectă `longitude = RA − GMST`
(standard Kenneth Bowser). Drift față de etalon: **< 1.5 km** la ecuator pentru
toate planetele.

### Răsărit / Apus de Soare (față de timeanddate.com)

| Locație | Dată | Parametru | Drift |
|---------|------|-----------|-------|
| Londra | 2026-04-15 | Răsărit | 0.6 s |
| Londra | 2026-04-15 | Apus  | 9 s   |

**Locații polare** (|lat| > 66.5°) returnează automat `polarState` +
warning că orele planetare obișnuite nu sunt definite.

### Orbi de aspecte

AstroWay folosește **orbi variabile** per-planetă (regula MIN a două planete),
ca în ZET9 și astro.com. Orbi implicit (pentru harta natală):

| Aspect | Soare | Lună | Interne | Jupiter | Externe |
|--------|-------|------|---------|---------|---------|
| Conjuncție | 12°  | 10° | 5° | 8° | 5° |
| Sextil     | 6.5° | 6°  | 5° | 5° | 5° |
| Pătrat     | 10°  | 8°  | 5° | 7° | 5° |
| Trigon     | 12°  | 8°  | 5° | 5° | 5° |
| Opoziție   | 12°  | 10° | 5° | 8° | 5° |

Aspectele minore (36°, 40°, 45°, 72°, 108°, 135°, 144°) sunt **dezactivate implicit**.
Se activează explicit prin `ALL_ASPECTS`.

## Latitudini polare

Pentru |lat| > 66.5° sistemele Placidus / Koch / Regiomontanus nu sunt definite
matematic. În astfel de cazuri, Swiss Ephemeris returnează automat Porphyry, iar
API-ul nostru adaugă un warning:

```json
{
  "system": "P",
  "warning": "Sistemul Placidus nu este definit pentru lat=68.96° (> 66.5°). Swiss Ephemeris a substituit cu Porphyry..."
}
```

## Verificare continuă

Regresia este verificată **la fiecare PR** prin CI:

- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshots față de hărți
  de referință (Monroe / Diana / Einstein) + synastry / composite / davison
- `.github/workflows/api-accuracy.yml` — rulare automată la PR
- Triangulație față de swetest CGI + Kerykeion — săptămânal
- Monitorizare upstream Swiss Ephemeris prin Dependabot

## Limitări cunoscute

- **Date în afara intervalului** (înainte de 1800 și după 2399): folosește Moshier
  analitic, precizie ~0.1" (față de < 0.01" pentru SWIEPH cu fișiere DE431)
- **Lilith adevărată (id=13) vs. Lilith medie (id=12)**: diferență de până la 12° —
  implicit folosește Lilith medie (comportament stabil), Lilith adevărată este
  disponibilă prin `planetIds: [13]`
- **Topocentric vs. geocentric**: implicit geocentric

## Linkuri

- Swiss Ephemeris: https://www.astro.com/swisseph/
- swetest CGI: https://www.astro.com/swisseph/swetest.htm
- Catalogul de eclipse NASA: https://eclipse.gsfc.nasa.gov/
- Kerykeion: https://github.com/g-battaglia/kerykeion
- Astrodienst: https://www.astro.com/

## Contacte

Pentru întrebări legate de precizie: scrie la support@astroway.info cu datele
hărții tale și sursa de referință așteptată (astro.com sau altă sursă autoritară).