astrololo/tests/oracle/README.md

# Porównanie domów z wyrocznią (Swiss Ephemeris)

Framework testowy do systemów domów. Liczenie cuspów traktujemy jako **funkcję**
parametrów `(RAMC, ε, φ)`, a **Swiss Ephemeris jako wyrocznię** — czyli niezależną
implementację, wobec której sprawdzamy naszą.

Powstał pod implementację systemów egzotycznych (Placidus, Koch, Regiomontanus,
Campanus…), gdzie błąd jest **cichy**: wykres wygląda poprawnie, tylko planety
siedzą w złych domach. Pojedyncze cuspy przepisane z internetu tego nie wyłapią —
tysiące porównań na całej dziedzinie tak.

## Dlaczego akurat tak

**Izolacja jednostki.** Obu implementacjom podajemy TE SAME wejścia przez
`swe_houses_armc`. Gdybyśmy porównywali „nasz horoskop" z „horoskopem swissepha",
różnica mogłaby wynikać z innego czasu gwiazdowego albo innego ε — czyli z czegoś,
co nie jest testowaną funkcją, i utonęlibyśmy w fałszywych alarmach.

**Czego ten framework NIE sprawdza — i trzeba o tym pamiętać.** Skoro ε podajemy
obu stronom, to **samo ε nie jest tu testowane**. Test `asc/mc` sprawdza wyłącznie
wzory na Ascendent i MC przy zadanym ε, a nie to, czy ε jest właściwe. Kosztowało
to realny błąd: silnik liczył RAMC z GAST (czas gwiazdowy POZORNY, od równonocy
PRAWDZIWEJ), ale parował go z ε ŚREDNIM, bez nutacji. Dwa różne układy odniesienia,
~3,2″ przesunięcia na cuspach — i komplet zielonych przebiegów wyroczni, bo błąd
siedział w danych WEJŚCIOWYCH, nie w testowanej funkcji.

Wejście ma więc własny sprawdzian, poza tym frameworkiem:
`test_sidereal_returns_true_obliquity_not_mean` w `services/logic/tests/`, ze
Skyfieldem jako niezależnym autorytetem (bez swissepha, więc działa wszędzie).

Uwaga pokrewna: porównanie „cały horoskop nasz vs cały horoskop swissepha" zostawia
resztę ~3″ nawet po naprawie ε — to UT1 kontra UTC. Skyfield konwertuje UTC na UT1
z tablic IERS, swisseph przyjmuje podany JD jako UT1 (w 1984-04-30 różnica wynosiła
0,181 s = 2,7″ RAMC). Nasza strona jest tu dokładniejsza. Dokładnie po to porównujemy
przy identycznym RAMC.

**Kryterium, nie procent.** Raportujemy liczbę przypadków **powyżej tolerancji
(1″)**, **maksymalne odchylenie** i **miejsce** jego wystąpienia oraz histogram.
Sam procent zgodności ukrywa kształt błędu: „97%" nie odróżnia szumu
zmiennoprzecinkowego od jednego rogu dziedziny, w którym mylimy się o 30°.

**Granice liczone per data.** Koło podbiegunowe — granica dziedziny Placidusa
i Kocha — **nie jest stałą 66,56°**. Zależy od ε, które zmienia się z datą (23,75°
w 370 p.n.e., 23,44° dziś), więc w zakresie programu przesuwa się o ~0,3°.

**Zgodność co do dziedziny.** Gdy wyrocznia odmawia liczenia (poza dziedziną),
a my uważamy, że liczymy — to też jest błąd, zgłaszany osobno. Wyrocznia mówi nam
zatem nie tylko *jakie są wartości*, ale i *gdzie kończy się dziedzina*.

## Uruchomienie

```bash
LOGIC_PATH=../../services/logic python run.py --mode build
```

| Tryb | Co robi | Gdzie działa |
|---|---|---|
| `--mode build` | zestaw **brzegowy** + tyle samo przypadków z wnętrza | CI, **blokuje** build |
| `--mode sweep --count N --seed S` | wielki **losowy** przemiał | Job w klastrze, nie blokuje |

Kod wyjścia: `0` = zgodność w granicach tolerancji, `1` = przekroczenia albo
niezgodność dziedziny. Ziarno jest zawsze raportowane — każdy błąd da się
**odtworzyć** komendą wypisaną w raporcie.

## Co ten framework już znalazł

Uruchomiony na kodzie, który uchodził za poprawny (whole sign / equal / porphyry),
wykrył **dwa realne błędy** w pierwszym przebiegu:

1. **Ascendent o 180° za kołem podbiegunowym.** `atan2` wybierał niewłaściwy punkt
   przecięcia ekliptyki z horyzontem — zwracaliśmy Descendent. Planety lądowały
   w przeciwnych domach dla całej północnej Skandynawii (Tromsø, Rovaniemi,
   Murmańsk). Dotyczyło ~11% przypadków na tych szerokościach.
2. **Niedeterminizm whole sign na granicy znaku.** Ascendent o włos od granicy
   (359,999999999976 vs 1e-10 — ta sama wartość, różne strony) przerzucał dom I
   o 30°. Ten sam horoskop na innej maszynie mógł dać inny wynik.

Oba mają teraz testy regresji w `services/logic/tests/test_houses.py`, więc są
łapane także bez swissepha.

## Stan systemów domów

Etap 1 — systemy o **zamkniętym wzorze** (bez iteracji). Każdy poniższy przeszedł
zarówno zestaw brzegowy (2520 porównań), jak i losowy przemiał 20 000 przypadków
(240 000 porównań na system):

| System | Konstrukcja | Maks. odchylenie |
|---|---|---|
| whole sign | podział ekliptyki | 0,000000000° |
| whole sign (od Barana) | dom I zawsze na 0° Barana | 0,000000000° |
| equal | podział ekliptyki od Ascendentu | 0,000000000° |
| equal (od MC) | dom X dokładnie na MC | 0,000000000° |
| porphyry | podział kwadrantów po ekliptyce | 0,000000000° |
| vehlow | equal z Ascendentem w środku domu I | 0,000000000° |
| morinus | równik rzutowany wprost na ekliptykę | 0,000000000° |
| regiomontanus | podział równika, koła przez punkty N/S horyzontu | 0,000000000° |
| campanus | podział wertykału pierwszego | 0,000000000° |
| alcabitus | podział łuków dobowych po równiku | 0,000000000° |
| topocentric | ascendenty pod biegunami tan(P) = tan(φ)·k/3 | 0,000000000° |

Etap 2 — systemy **łuku dobowego**, jedyne z realną granicą dziedziny:

| System | Konstrukcja | Maks. odchylenie |
|---|---|---|
| placidus | trójdzielenie półłuków, iteracyjnie | 0,000001686° |
| koch | trójdzielenie CZASU od wschodu stopnia MC | 0,000000000° |

Placidus jest jedynym systemem bez wzoru zamkniętego: cusp jest zdefiniowany
warunkiem na samego siebie, więc szukamy go iteracyjnie do 1e-11°. Pozostałe
1,7e-6° to **próg zbieżności wyroczni**, nie nasz błąd — nasz cusp spełnia
definicję Placidusa z dokładnością 1e-12° (test `test_placidus_cusps_satisfy_
their_own_definition` sprawdza to bez swissepha).

Powyżej koła podbiegunowego oba **odmawiają liczenia** — i wyrocznia odmawia
dokładnie tych samych przypadków (5245 na 20 000 losowych, zero rozjazdów).
Warstwa aplikacyjna łapie tę odmowę i podstawia Porphyry'ego z **głośnym
komunikatem**, który idzie na ekran, w prompt do modelu i do PDF-a: po podmianie
kosmogram wygląda bezbłędnie, więc jest to jedyny sygnał dla astrologa.

### Topocentric — i czego nauczył

Topocentric był początkowo **wycofany** z powodu rozjazdu przy |φ| ≈ 89,9°.
Ta diagnoza była **błędna**, bo opierała się wyłącznie na zestawie brzegowym,
który próbkuje tylko wybrane szerokości. Przemiał losowy pokazał prawdziwą skalę:
błędy zaczynały się już od ~70° i sięgały 50% przypadków blisko biegunów —
**6,5% całości**, nie dwa przypadki brzegowe.

Przyczyną nie była jednak konstrukcja, tylko wybór gałęzi. Dwa koła wielkie
przecinają się w dwóch punktach antypodycznych i trzeba wskazać właściwy.
Kolejno zawiodły: „po której stronie MC", „w łuku kwadrantu", „wschodnia połowa
horyzontu" oraz śledzenie ciągłości krokami. Każda z nich rozstrzyga **lokalnie**,
a przy dużych szerokościach kolejność domów potrafi się odwrócić — przy φ = −79,55°
MC wypada na 306,8°, a dom 11 na 291,4°, czyli domy biegną wstecz. To jest poprawne
i wyrocznia zwraca dokładnie to samo.

Rozwiązaniem było **nie wybierać w ogóle**. Iloczyn wektorowy zenitu z biegunem
ekliptyki jest ciągłą funkcją parametru rodziny i sam niesie właściwy zwrot;
dwuznaczność wprowadza dopiero `atan2`. Zostając w wektorach i kotwicząc rodzinę
raz — na MC górującym — dostajemy zgodność **co do zera na całej dziedzinie**,
bez iteracji i bez zawężania szerokości.

Morał praktyczny: zestaw brzegowy mówi, **czy** system się psuje; dopiero przemiał
losowy mówi **jak bardzo**. Wniosek o skali wyciągnięty z samych brzegów był tu
zaniżony o trzy rzędy wielkości.

Większe jądro efemeryd (de441) — **odłożone, „nice to have"**: rozszerza tylko
zakres dat, nie poprawia niczego w obecnym.

## Licencja

Swiss Ephemeris jest na AGPL i jest tu **wyłącznie wyrocznią testową** — nie wchodzi
do ścieżki produkcyjnej ani do zależności produktu. Izolacja z LOG-27 zostaje
nienaruszona.