astrololo/docs/architektura-dwoch-silnikow.md

Architektura dwóch silników (warstwa logiczna)

Dokument roboczy. Decyzja: warstwa logiczna ma dwie wymienne implementacje silnika obliczeń — jedną własną/permisywną (ścieżka A) i jedną opartą o AGPL (ścieżka C, Swiss Ephemeris) — żeby od pierwszego dnia mieć wbudowany framework porównań i walidacji. Warstwy prezentacji i danych pozostają wspólne i pojedyncze; rozdwaja się wyłącznie silnik wewnątrz warstwy logicznej.

---

1. Schemat

            (jedna)                         (jedna, ale 2 silniki)                (jedna)
┌──────────────────────┐        ┌─────────────────────────────────────┐        ┌──────────────────────┐
│      PREZENTACJA      │ ─────▶ │             LOGIKA                  │ ─────▶ │        DANE          │
│   (bez zmian)         │ ◀───── │   EngineProvider (interfejs)        │ ◀───── │   (bez zmian)        │
└──────────────────────┘        │     ├── EngineA: własny (permisywny)│        └──────────────────────┘
                                 │     │     Skyfield/Moshier — in-proc │
                                 │     └── EngineB: swisseph (AGPL)     │
                                 │           ⇢ OSOBNY proces/usługa     │
                                 │     Komparator (dual-run + raport)   │
                                 └─────────────────────────────────────┘
                                                   │
                                                   ⇢ (granica sieciowa/IPC)
                                       ┌─────────────────────────────────┐
                                       │  engine-swisseph (AGPL, OSOBNO)  │
                                       │  pyswisseph / Swiss Ephemeris    │
                                       └─────────────────────────────────┘

Prezentacja i dane „widzą" tylko interfejs EngineProvider — nie wiedzą, który silnik liczy (engine‑agnostic). To ta sama zasada modułowości co DataProvider w warstwie danych.

---

2. Po co dwa silniki

1. Wyrocznia walidacyjna od dnia zero. Każdy wynik EngineA możemy natychmiast porównać z EngineB (Swiss Ephemeris = de‑facto standard). Bezcenne przy budowie własnego silnika od zera (primary directions, domy, węzły/Lilith).
2. Framework porównań. Tryb „policz oboma i pokaż różnice" — do testów regresyjnych (CI) i do podglądu side‑by‑side w UI.
3. Bezpieczeństwo decyzji. Gdyby własny silnik gdzieś odstawał, widać to od razu, a nie po miesiącach.

---

3. Izolacja licencyjna (warunek konieczny) ⚠️

EngineB jest AGPL, więc nie może być wlinkowany w permisywny produkt. Rozwiązanie zgodne z naszą architekturą (osobne usługi jak warstwa danych):

• EngineB = osobny proces/usługa engine-swisseph, wołany przez granicę sieciową/IPC (HTTP). Brak linkowania = brak „zarażenia" copyleftem reszty.
• Produkt zamknięty (dystrybucja/hosting): prezentacja + logika(EngineA) + dane. Bez EngineB. Zero AGPL.
• Profil porównawczy/dev/CI: dodatkowo uruchamiamy usługę engine-swisseph (AGPL, sama w sobie zgodna z AGPL — to w zasadzie cienkie API na pyswisseph). Używana wewnętrznie do porównań, nie wystawiana użytkownikom produktu.
• Konfiguracja decyduje, czy EngineB jest w ogóle dostępny (ENGINE_B_URL ustawione lub nie).

Efekt: pełny framework porównań bez narażania kodu i danych produktu na obowiązki AGPL (patrz przeglad-bibliotek-i-licencji.md oraz analiza zakresu AGPL względem baz danych).

---

4. Jak działa porównanie (dual‑run)

1. To samo wejście (dane horoskopu + ustawienia) trafia do EngineA i EngineB.
2. Komparator zestawia wyniki: pozycje obiektów, cusps domów, aspekty, daty technik.
3. Różnice liczone z progami tolerancji per wielkość (np. długość ekliptyczna ≤ 1″, cusp ≤ 1″, data zdarzenia ≤ 1 min); przekroczenia oflagowane.
4. Raport: (a) jako asercje w CI (regresja), (b) jako podgląd side‑by‑side w prezentacji na żądanie.

---

5. Wpływ na warstwy i mapowanie na wymagania

Warstwa	Zmiana
Prezentacja	brak (opcjonalnie: widok porównawczy side‑by‑side)
Dane	brak
Logika	EngineProvider + 2 backendy (EngineA in‑proc, EngineB jako klient usługi AGPL) + komparator
Nowa usługa	engine-swisseph (AGPL, osobno, opcjonalna)

Wymagania (arkusz „Warstwa logiczna"):

• LOG‑24 — interfejs EngineProvider z dwoma backendami (zrewidowane).
• LOG‑25 — framework walidacyjno‑porównawczy (zrewidowane).
• LOG‑26 — tryb dual‑run + raport różnic (nowe).
• LOG‑27 — izolacja licencyjna silnika AGPL jako osobnej usługi (nowe).
• LOG‑28 — kontrakt parzystości silników: identyczny interfejs, te same testy (nowe).

---

6. Implikacje wdrożeniowe

• Dwa profile docker-compose: proprietary (prezentacja+logika+dane, EngineA) i comparison (dodaje engine-swisseph).
• Testy kontraktowe uruchamiane na obu silnikach (ten sam zestaw → gwarancja parzystości interfejsu).
• Decyzja A vs B na produkcji pozostaje po stronie A; B nigdy nie trafia do dystrybucji zamkniętej — służy jako wzorzec i narzędzie QA.