# Hesaplama doğruluğu

## TL;DR

AstroWay API kullanıyor **Swiss Ephemeris** (Astrodienst'in resmi C kodu,
astro.com'un yaratıcıları), yani profesyonel astrologların **30+ yıldır**
çalıştığı **Solar Fire ($495), Kepler ($995), Astro Gold ($29.99/ay) ve Janus**
için kullanılan aynı motor. Bunu WebAssembly'e derledik ve aracısız bir REST
API katmanıyla sunduk. Her temel hesaplama endpointi regression snapshot
testleriyle kapsanmıştır; motor doğruluğu **üç bağımsız kaynaktan triangülasyon**
ve **NASA 5-Millennium Eclipse Catalog** karşılaştırmasıyla doğrulanmıştır:

- **Gezegen pozisyonları**: `< 0.1 yay saniyesi` resmi Astrodienst swetest CGI
  karşısında
- **Placidus ev kuspitleri**: `0.000"` tam eşleşme
- **Tutulmalar**: `< 1 dakika` NASA Eclipse Catalog karşısında
- **ACG hatları**: Ekvatorda `< 1.5 km` swetest karşısında
- **Gün doğumu/batımı**: `< 10 saniye` timeanddate.com karşısında
- **Ay VOC, girişler, gezegen kavuşumları**: saniyenin kesirlerine kadar hassasiyet

## Motor

| Bileşen | Değer |
|---------|-------|
| Kütüphane | Swiss Ephemeris C kodu (aloistr/swisseph) |
| Sürüm | upstream Astrodienst C kodu |
| Bağlantılar | swisseph-wasm (Node.js için WebAssembly) |
| Efemeris | DE431 JPL efemeris (.se1 dosyaları üzerinden) |
| Yedek | Moshier analitik (1800-2399 dışındaki tarihler için) |
| Code sharing | Shared `@/core` app.astroway.info ile — tek motor, iki taşıyıcı |

## Doğrulama Yöntemi

Doğruluk **üçgenleme** yoluyla doğrulanır — üç bağımsız kaynağa karşı karşılaştırma:

### 1. swetest CGI (referans)

Astrodienst'in kendisinin yarattığı Swiss Ephemeris'in resmi referans
uygulaması — **Astro.com**'u oluşturan komutlar ve dünya çapındaki milyonlarca
astrologu destekliyor. En yetkili kamu kaynağı. Motorumuz **tamamen aynı**
(0.00–0.07 yay saniyesi sapma).

### 2. Kerykeion (Python)

Bağımsız Python kütüphanesi, bizim WASM'imiz yerine `pyswisseph` bağlantıları
kullanıyor. WASM katmanımızın verileri bozmadığını doğruluyor.

### 3. Prokerala API

Uzak Swiss Ephemeris API'si (sidereal Lahiri). 8–17 yay saniyesi sistematik
sapma, farklı Lahiri ayanamsa formülü sürümleriyle ilgili (**motor doğruluğuyla
ilgili değil**).

## Üçgenleme Sonuçları

| Harita | swetest (Astrodienst) karşısında | Kerykeion (Python) karşısında | Prokerala API karşısında |
|--------|----------------------------------|-------------------------------|--------------------------|
| Monroe 1926   | **0.00"** | 0.19" | 16.95" (sistematik) |
| Diana 1961    | **0.00"** | 0.69" | 8.18" (sistematik)  |
| Einstein 1879 | 0.07"     | Kerykeion LMT artifact | 14.96" (sistematik) |

## Endpoint Düzeyinde Regression Seti

Temel hesaplama endpointlerinin her biri 3 referans haritası (Monroe / Diana /
Einstein) üzerinde dondurulmuş snapshot testleriyle kapsanmıştır — **{siteMeta.snapshotCount} snapshot**.

Snapshot seti yakalar:

- **Girdi verilerinin haritalama hataları** — yanlış gezegen id'si, UT, ev sistemi
- **Son işlem** — yuvarlama, birim dönüşümü, işaret kaybı
- **Varsayılan farklılıkları** — mean vs true node, jeosentrik vs topocentrik
- **Schema drift** — doğrulama yanlış bir formu kaçırdı
- **Eski dağıtım** — prod dist kodla uyumlu değil

Tolerans: Tüm sayısal alanlar için varsayılan olarak `5e-5°` (≈0.18 yay saniyesi).

## Detaylı Benchmarklar

### Gezegen Pozisyonları (tropik, swetest karşısında)

| Harita | Tarih | Maksimum sapma |
|--------|-------|----------------|
| Marilyn Monroe  | 1926-06-01 | **0.00"** |
| Princess Diana  | 1961-07-01 | **0.00"** |
| Albert Einstein | 1879-03-14 | 0.07"     |

### Placidus Ev Kuspileri (swetest karşısında)

| Harita | drift ASC | drift MC | Maksimum kuspit sapması |
|--------|-----------|----------|--------------------------|
| Monroe | 0.000" | 0.000" | 0.000" |
| Diana  | 0.000" | 0.000" | 0.000" |

### Tutulmalar (NASA 5-Millennium Catalog karşısında)

| Olay | NASA maksimumu | Bizim maksimum | Sapma |
|------|----------------|----------------|-------|
| 2025-03-14 Ay Tutulması  | 06:58 UT | 06:58 UT | 0.8 dk |
| 2025-03-29 Güneş Tutulması | 10:47 UT | 10:47 UT | 0.5 dk |
| 2025-09-07 Ay Tutulması  | 18:11 UT | 18:11 UT | 0.8 dk |
| 2025-09-21 Güneş Tutulması | 19:41 UT | 19:42 UT | 1.0 dk |

### Astrokartografi (swetest RA formülü karşısında)

Tüm MC/IC/ASC/DSC hatları doğru `longitude = RA − GMST` formülünü kullanır
(Kenneth Bowser standardı). Sapma: **tüm gezegenler için ekvatorda < 1.5 km**.

### Güneş Doğuşu / Batışı (timeanddate.com karşısında)

| Lokasyon | Tarih | Parametre | Sapma |
|----------|-------|-----------|-------|
| Londra | 2026-04-15 | Gün doğumu | 0.6 sn |
| Londra | 2026-04-15 | Gün batımı  | 9 sn   |

**Kutup bölgeleri** (|enlem| > 66.5°) otomatik olarak `polarState` + normal
gezegensel saatlerin tanımlanmadığına dair uyarı döndürür.

### Aspekt Orb'ları

AstroWay **değişken orb'ları** kullanır (iki gezegenin MIN kuralı), tıpkı ZET9
ve astro.com'da olduğu gibi. Varsayılan orb'lar (natal harita için):

| Aspekt | Güneş | Ay | İç Gezegenler | Jüpiter | Dış Gezegenler |
|--------|-------|----|---------------|---------|----------------|
| Kavuşum | 12°  | 10° | 5° | 8° | 5° |
| Altıgen | 6.5° | 6°  | 5° | 5° | 5° |
| Kare    | 10°  | 8°  | 5° | 7° | 5° |
| Üçgen   | 12°  | 8°  | 5° | 5° | 5° |
| Karşıt  | 12°  | 10° | 5° | 8° | 5° |

Minör aspektler (36°, 40°, 45°, 72°, 108°, 135°, 144°) **varsayılan olarak
kapalıdır**. `ALL_ASPECTS` ile açıkça etkinleştirilir.

## Kutup Enlemleri

|enlem| > 66.5° için Placidus / Koch / Regiomontanus sistemleri matematiksel olarak
tanımlanmamıştır. Bu durumlarda Swiss Ephemeris otomatik olarak Porphyry
döndürür ve API'miz bir uyarı ekler:

```json
{
  "system": "P",
  "warning": "Placidus sistemi enlem=68.96° (> 66.5°) için tanımlanmamıştır. Swiss Ephemeris Porphyry'yi kullanıyor..."
}
```

## Sürekli Doğrulama

Regression, her PR'de CI üzerinden doğrulanır:

- `api-calc/tests/endpoints/` — {siteMeta.snapshotCount} snapshot Monroe / Diana /
  Einstein + senastri / kompozit / Davison referans haritaları karşısında
- `.github/workflows/api-accuracy.yml` — PR'da otomatik çalıştırma
- Haftalık swetest CGI + Kerykeion karşısında üçgenleme
- Dependabot üzerinden upstream Swiss Ephemeris izleme

## Bilinen Sınırlamalar

- **Tarih aralığı dışı** (1800 öncesi ve 2399 sonrası): Moshier analitik
  kullanılır, hassasiyet ~0.1" (DE431 dosyalarıyla SWIEPH < 0.01" karşısında)
- **True Lilith (id=13) vs Mean Lilith (id=12)**: 12° fark — varsayılan olarak
  Mean Lilith (daha kararlı davranış), True Lilith `planetIds: [13]` üzerinden
  kullanılabilir
- **Topocentrik vs jeosentrik**: varsayılan olarak jeosentrik

## Bağlantılar

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

## İletişim

Doğrulukla ilgili sorular için: destek@astroway.info adresine harita verileri
ve beklenen referans (astro.com ya da başka yetkili kaynak) ile birlikte
yazabilirsin.