astrodemo: do obrazu wchodzi wyłącznie kod aplikacji

`COPY . .` wnosiło do obrazu cały katalog usługi, razem z tests/. Leży tam plik
pilnujący, żeby pewne słowa nie padły — wypisujący je wprost, bo inaczej nie da
się ich sprawdzić. Trafiając do obrazu, stawał się dokładnie tym wyciekiem,
przed którym broni: „pełna aplikacja", „astrololo", nazwy nieobecnych funkcji.

Obraz tej usługi się KOMUŚ ODDAJE, więc waży to więcej niż gdzie indziej.
To samo zawężenie zrobiłem wcześniej w warstwie prezentacji; astrodemo zostało
przeoczone, bo powstało przed tamtą zmianą.

Test pilnuje tego na przyszłość i czyta same instrukcje, bez komentarzy —
komentarz obok cytuje dawną postać, więc szukanie po całym pliku zgłaszałoby
własne wyjaśnienie.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,33 @@
+# Kontekst builda dla obrazów budowanych z KORZENIA repo (dziś: pomocniczy obraz
+# wyroczni w CI — patrz .gitea/workflows/tests.yml). Obrazy usług mają własne
+# konteksty (services/<usługa>), więc ten plik ich nie dotyczy.
+#
+# UWAGA: docker NIE czyta .gitignore. Bez tego pliku do demona poleciałby m.in.
+# lokalny wirtualenv (~344 MB) i jądra efemeryd — a runner miał już incydent
+# „no space left on device".
+
+# środowiska lokalne
+.env/
+.venv/
+venv/
+
+# cache Pythona i narzędzi
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# dane generowane/pobierane, odtwarzalne
+**/.ephemeris/
+**/.cache/
+
+# historia i metadane repo
+.git/
+.gitea/
+.claude/
+
+# rzeczy nieużywane w obrazach
+docs/
+*.md

.env.example

@@ -0,0 +1,17 @@
+# Skopiuj do .env i dostosuj.
+
+# --- warstwa bazodanowa ---
+DATA_PROVIDER=excel          # excel | sql
+EXCEL_DIR=./services/data/data_files
+CACHE_DIR=./services/data/.cache
+INDEXED_KEYS=name,id,symbol
+HEADER_SCAN_ROWS=15
+QUERY_CACHE_SIZE=512
+QUERY_CACHE_TTL=300
+SQL_URL=sqlite:///./.cache/astrololo.db
+
+# --- warstwa logiczna ---
+DATA_URL=http://localhost:8002
+
+# --- warstwa prezentacji ---
+LOGIC_URL=http://localhost:8001

.gitea/workflows/build-render.yaml

@@ -0,0 +1,34 @@
+name: build-render
+
+# Osobny pipeline dla uslugi render (raport PDF, PRE-24) — celowo ODDZIELONY od
+# glownego build.yaml (data/logic/presentation). Obraz dzwiga TeX Live (setki MB),
+# wiec budowanie go przy KAZDYM pushu do mastera spowalnialoby kazdy deploy — a to
+# wlasnie ta izolacja mial usunac (patrz services/render/app/main.py, LOG-27).
+# Buduje sie tylko, gdy zmienia sie sama usluga.
+#
+# Obraz konsumuje astrololo/render.yaml w repo `deploy`.
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'services/render/**'
+      - '.gitea/workflows/build-render.yaml'
+  workflow_dispatch: {}          # reczne odpalenie (bootstrap pierwszego obrazu)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Login
+        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login gitea.czernobog.pl -u gitea --password-stdin
+      - name: Build & push render (TeX Live — pierwszy build trwa dluzej)
+        run: |
+          TAG=${GITHUB_SHA::8}
+          IMG=gitea.czernobog.pl/gitea/astrololo-render
+          # Dockerfile sprawdza obecnosc xelatex + rsvg-convert przy budowie, wiec
+          # build jest zarazem testem, ze obraz ma komplet narzedzi.
+          docker build -t $IMG:$TAG -t $IMG:latest ./services/render
+          docker push $IMG:$TAG
+          docker push $IMG:latest
+          echo "Zbudowano i wypchnieto: $IMG:$TAG (+ latest)"

.gitea/workflows/build-swisseph.yaml

@@ -0,0 +1,32 @@
+name: build-swisseph
+
+# Osobny pipeline dla silnika B (Swiss Ephemeris, AGPL) — celowo ODDZIELONY od
+# głównego build.yaml (data/logic/presentation). Buduje się tylko, gdy zmienia się
+# sam silnik, i nie miesza obrazu AGPL do pipeline'u permisywnego produktu.
+#
+# Obraz konsumuje profil deployu `astrololo-swisseph` w repo `deploy`.
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'services/engine-swisseph/**'
+      - '.gitea/workflows/build-swisseph.yaml'
+  workflow_dispatch: {}          # ręczne odpalenie (bootstrap pierwszego obrazu)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Login
+        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login gitea.czernobog.pl -u gitea --password-stdin
+      - name: Build & push engine-swisseph (AGPL, izolowany)
+        run: |
+          TAG=${GITHUB_SHA::8}
+          IMG=gitea.czernobog.pl/gitea/astrololo-engine-swisseph
+          # Obraz kompiluje pyswisseph ze źródeł (brak wheeli dla cp312) — build jest
+          # zarazem realnym testem Dockerfile'a.
+          docker build -t $IMG:$TAG -t $IMG:latest ./services/engine-swisseph
+          docker push $IMG:$TAG
+          docker push $IMG:latest
+          echo "Zbudowano i wypchnięto: $IMG:$TAG (+ latest)"

.gitea/workflows/build.yaml

@@ -0,0 +1,21 @@
+name: build
+on:
+  push:
+    branches: [master]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Login
+        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login gitea.czernobog.pl -u gitea --password-stdin
+      # astrodemo dołącza do tej samej pętli: dzieli warstwę logiczną i łącze,
+      # więc jego obraz ma powstawać z tego samego commita co reszta produktu.
+      - name: Build & push (data, logic, presentation, astrodemo)
+        run: |
+          TAG=${GITHUB_SHA::8}
+          for SVC in data logic presentation astrodemo; do
+            docker build -t gitea.czernobog.pl/gitea/astrololo-$SVC:$TAG ./services/$SVC
+            docker push  gitea.czernobog.pl/gitea/astrololo-$SVC:$TAG
+          done
+          echo "Tag: $TAG"

.gitea/workflows/oracle-sweep.yaml

@@ -0,0 +1,59 @@
+name: Wyrocznia domów — nocny przemiał
+
+# DLACZEGO TU, A NIE JAKO JOB W KLASTRZE
+# Pierwotny plan zakładał CronJob w k3s, bo „duży przemiał jest kosztowny".
+# Pomiar tego nie potwierdził: 500 000 przypadków × 13 systemów = 70 mln porównań
+# w 64 sekundy, skalowanie liniowe. Osobny obraz w rejestrze (który już raz zapchał
+# dysk hosta), manifest, CronJob i kopia harnessu poza repo byłyby infrastrukturą
+# do problemu, którego nie ma — a każda kopia harnessu poza repo to ryzyko cichego
+# rozjazdu z kodem, który ma testować.
+#
+# Zestaw brzegowy blokuje KAŻDY build (patrz tests.yml). Tutaj chodzi o co innego:
+# duża losowa próbka z INNYM ZIARNEM co noc, żeby z czasem przeczesać dziedzinę
+# gęściej, niż zrobi to pojedynczy przebieg.
+on:
+  schedule:
+    - cron: '17 2 * * *'         # 02:17 — poza godzinami budowania
+  workflow_dispatch:
+    inputs:
+      count:
+        description: 'Liczba przypadków'
+        default: '500000'
+      seed:
+        description: 'Ziarno (puste = z daty)'
+        default: ''
+
+jobs:
+  sweep:
+    name: Przemiał losowy (13 systemów)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Obraz wyroczni (silnik B + nasza logika + harness)
+        run: |
+          docker build -t astrololo/engine-swisseph:sweep services/engine-swisseph
+          # Pliki WBUDOWANE, nie montowane: job Gitea Actions sam działa w kontenerze,
+          # więc `-v $PWD/...` rozwiązałoby się na HOŚCIE (docker cicho tworzy pusty
+          # katalog i skrypt „znika"). Kontekst builda jest strumieniowany do demona.
+          docker build -t astrololo/oracle:sweep -f - . <<'DOCKERFILE'
+          FROM astrololo/engine-swisseph:sweep
+          COPY services/logic /logic
+          COPY tests/oracle /oracle
+          ENV LOGIC_PATH=/logic
+          DOCKERFILE
+
+      - name: Przemiał
+        run: |
+          COUNT="${{ inputs.count }}"; COUNT="${COUNT:-500000}"
+          SEED="${{ inputs.seed }}"; SEED="${SEED:-$(date -u +%Y%m%d)}"
+          echo "count=$COUNT seed=$SEED"
+          # Kod wyjścia 1 przy przekroczeniu tolerancji ALBO niezgodności dziedziny,
+          # więc job czerwieni się sam — bez parsowania tekstu raportu.
+          docker run --rm astrololo/oracle:sweep \
+            python /oracle/run.py --mode sweep --count "$COUNT" --seed "$SEED"
+
+      # Runner miał już incydent „no space left on device" — sprzątamy zawsze.
+      - name: Usuń obrazy pomocnicze
+        if: always()
+        run: docker rmi -f astrololo/oracle:sweep astrololo/engine-swisseph:sweep 2>/dev/null || true

.gitea/workflows/tests.yml

@@ -0,0 +1,242 @@
+name: Testy
+
+# Odpala się przy każdym pushu (dowolna gałąź) oraz dla pull requestów do master.
+on:
+  push:
+  pull_request:
+    branches: [master]
+
+jobs:
+  logic-tests:
+    name: Testy warstwy logicznej (silnik)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Python 3.12 (jak w obrazach Dockera)
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: services/logic/requirements-dev.txt
+
+      # Jądro efemeryd JPL (de421.bsp, ~17 MB). Cache'ujemy je między runami.
+      - name: Cache jądra efemeryd
+        uses: actions/cache@v4
+        with:
+          path: services/logic/.ephemeris
+          key: ephemeris-de421
+
+      # Pobieramy jawnie (a nie licząc na auto-pobranie przez Skyfield), żeby
+      # brak jądra był twardym błędem, a nie cichym pomijaniem testów.
+      - name: Pobierz jądro efemeryd (gdy brak w cache)
+        run: |
+          mkdir -p services/logic/.ephemeris
+          if [ ! -s services/logic/.ephemeris/de421.bsp ]; then
+            curl -fSL --retry 3 --max-time 300 \
+              -o services/logic/.ephemeris/de421.bsp \
+              https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/de421.bsp
+          fi
+          ls -lh services/logic/.ephemeris/de421.bsp
+
+      - name: Instalacja zależności
+        run: pip install -r services/logic/requirements-dev.txt
+
+      # CI=true (ustawiane przez GitHub) sprawia, że brak silnika = błąd,
+      # a nie pominięcie — patrz tests/conftest.py.
+      - name: Testy (pytest)
+        working-directory: services/logic
+        env:
+          PYTHONPATH: .
+          EPHEMERIS_DIR: ${{ github.workspace }}/services/logic/.ephemeris
+        run: pytest tests -q -rs
+
+  presentation-tests:
+    name: Testy warstwy prezentacji (dostęp do baz)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: services/presentation/requirements-dev.txt
+      - name: Instalacja zależności
+        run: pip install -r services/presentation/requirements-dev.txt
+      # Bramka chroniąca oryginalne bazy — nietestowany kod ochronny jest gorszy
+      # niż jego brak, bo daje złudzenie zabezpieczenia.
+      - name: Testy (pytest)
+        working-directory: services/presentation
+        env:
+          PYTHONPATH: .
+        run: pytest tests -q -rs
+
+  data-tests:
+    name: Testy warstwy bazodanowej (ochrona baz)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: services/data/requirements-dev.txt
+      - name: Instalacja zależności
+        run: pip install -r services/data/requirements-dev.txt
+      # Rekordy-pułapki (DAN-26): nietestowany kod ochronny jest gorszy niż jego
+      # brak, bo daje złudzenie zabezpieczenia. Ta warstwa dotąd nie miała testów.
+      - name: Testy (pytest)
+        working-directory: services/data
+        env:
+          PYTHONPATH: .
+        run: pytest tests -q -rs
+
+  astrodemo-tests:
+    name: Testy astrodemo
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: services/astrodemo/requirements-dev.txt
+      - name: Instalacja zależności
+        run: pip install -r services/astrodemo/requirements-dev.txt
+      # Demo rozmawia z warstwą danych PRODUKCJI, więc jego powierzchnia musi być
+      # pilnowana tak samo jak reszty: testy sprawdzają m.in., że nie przybyła
+      # żadna trasa poza dwiema funkcjami.
+      - name: Testy (pytest)
+        working-directory: services/astrodemo
+        env:
+          PYTHONPATH: .
+        run: pytest tests -q -rs
+
+  swisseph-image:
+    name: Build obrazu silnika B (swisseph)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Obraz kompiluje pyswisseph ze źródeł (brak wheeli dla cp312), więc ten
+      # build jest realnym testem Dockerfile'a — nie tylko pobraniem paczek.
+      - name: docker build
+        run: docker build -t astrololo/engine-swisseph:ci services/engine-swisseph
+
+      # Test biegnie WEWNĄTRZ obrazu, bez sieci i bez kontenera w tle. Poprzednia
+      # wersja startowała kontener w tle (--name swe) i pukała curl-em w
+      # localhost:8003 — co miało dwie wady:
+      #   1. nie sprzątała kontenera, więc każdy kolejny przebieg padał na
+      #      konflikcie nazwy (Conflict. The container name "/swe" is already in use),
+      #   2. job Gitea Actions sam działa w kontenerze, a -p publikuje port na
+      #      HOŚCIE — więc localhost joba to nie ten sam localhost.
+      # Wywołanie funkcji endpointów wprost omija oba problemy, a sprawdza to samo:
+      # obraz się zbudował, pyswisseph liczy, kontrakt /positions się zgadza.
+      # --rm gwarantuje, że nic nie zostaje po przebiegu.
+      - name: Smoke test (health + pozycje) wewnątrz obrazu
+        run: |
+          docker run --rm astrololo/engine-swisseph:ci python - <<'PY'
+          from datetime import datetime, timezone
+
+          from app.main import DEFAULT_OBJECTS, PositionsRequest, health, positions
+
+          h = health()
+          assert h["status"] == "ok", h
+          print("health:", h)
+
+          # Horoskop referencyjny (30.04.1984) — ten sam, na którym opieramy testy
+          # silnika własnego; sprawdzamy, że silnik B faktycznie liczy.
+          req = PositionsRequest(when_utc=datetime(1984, 4, 30, 9, 20, tzinfo=timezone.utc),
+                                 lat=50.0647, lon=19.9450)
+          out = positions(req)
+          by = {p["name"]: p for p in out["positions"]}
+
+          assert out["engine"] == "swisseph", out["engine"]
+          assert len(by) == len(DEFAULT_OBJECTS), sorted(by)
+          sun = by["Sun"]["longitude"]
+          assert 39.5 < sun < 41.0, f"Slonce poza oczekiwanym zakresem: {sun}"
+          nn, sn = by["North Node"]["longitude"], by["South Node"]["longitude"]
+          assert abs(((sn - nn) % 360.0) - 180.0) < 1e-6, (nn, sn)
+
+          print(f"Sun={sun:.4f}  NN={nn:.4f}  obiektow={len(by)}")
+
+          # /houses — kontrakt parzystosci (LOG-28) po stronie DOMOW. Sprawdzamy
+          # nie tylko, ze liczy, ale i ze ODMAWIA tam, gdzie system nie istnieje:
+          # ciche podstawienie innego systemu byloby niewykrywalne dla wolajacego.
+          from fastapi import HTTPException
+
+          from app.main import _HOUSE_CODES, HousesRequest, houses
+
+          WHEN = "1984-04-30T09:20:00Z"
+          h = houses(HousesRequest(when_utc=WHEN, lat=50.0647, lon=19.9450, system="campanus"))
+          assert h["engine"] == "swisseph" and h["system"] == "campanus"
+          assert len(h["cusps"]) == 12, h["cusps"]
+          assert [c["house"] for c in h["cusps"]] == list(range(1, 13))
+          assert all(0.0 <= c["longitude"] < 360.0 for c in h["cusps"])
+          assert {"Asc", "MC", "ARMC"} <= set(h["angles"]), h["angles"]
+
+          # kazdy ogloszony system musi dac 12 cuspow tam, gdzie ma definicje
+          for name in _HOUSE_CODES:
+              out = houses(HousesRequest(when_utc=WHEN, lat=50.0647, lon=19.9450, system=name))
+              assert len(out["cusps"]) == 12, name
+          print(f"/houses: {len(_HOUSE_CODES)} systemow OK")
+
+          for bad, why in ((dict(lat=69.65, lon=18.96, system="placidus"), "Tromso/placidus"),
+                           (dict(lat=50.0, lon=19.0, system="nie-ma-takiego"), "nieznany system")):
+              try:
+                  houses(HousesRequest(when_utc=WHEN, **bad))
+                  raise AssertionError(f"{why}: mialo byc 422, a przeszlo")
+              except HTTPException as e:
+                  assert e.status_code == 422, (why, e.status_code)
+          print("/houses: odmowy poza dziedzina OK")
+
+          print("SMOKE OK")
+          PY
+
+      # Zgodność naszych domów z wyrocznią (Swiss Ephemeris). Odpalamy WEWNĄTRZ
+      # obrazu silnika B — tylko tam jest pyswisseph — montując naszą warstwę
+      # logiczną i framework. Bez klastra i bez HTTP: to czysta funkcja.
+      # BLOKUJE build: błędny system domów jest CICHY (wykres wygląda dobrze,
+      # planety siedzą w złych domach), więc lepiej zatrzymać go przed wypuszczeniem
+      # niż wykryć po fakcie.
+      - name: Domy — zgodność z wyrocznią (brzegi + wnętrze)
+        run: |
+          # Pliki WBUDOWUJEMY w obraz, a nie montujemy przez -v. Powód ten sam,
+          # dla którego wyżej nie startujemy kontenera w tle: job Gitea Actions sam
+          # działa w kontenerze, więc `-v $PWD/...` docker rozwiązuje na HOŚCIE,
+          # gdzie tej ścieżki nie ma. Docker nie zgłasza wtedy błędu — po cichu
+          # tworzy PUSTY katalog, przez co skrypt „znika". Kontekst builda jest
+          # strumieniowany do demona, więc działa niezależnie od tego, gdzie on stoi.
+          docker build -t astrololo/oracle:ci -f - . <<'DOCKERFILE'
+          FROM astrololo/engine-swisseph:ci
+          COPY services/logic /logic
+          COPY tests/oracle /oracle
+          ENV LOGIC_PATH=/logic
+          DOCKERFILE
+          docker run --rm astrololo/oracle:ci python /oracle/run.py --mode build
+
+      # Obraz pomocniczy nie jest już potrzebny — a runner miał już incydent
+      # „no space left on device", więc sprzątamy po sobie od razu.
+      - name: Usuń obraz pomocniczy wyroczni
+        if: always()
+        run: docker rmi -f astrololo/oracle:ci 2>/dev/null || true
+
+      # Sprzątanie po POPRZEDNICH przebiegach starej wersji workflow, która
+      # zostawiała kontener „swe" na runnerze i blokowała nazwę. Nowa wersja
+      # kontenera w tle nie tworzy, więc to tylko jednorazowe uprzątnięcie.
+      - name: Usuń osierocony kontener ze starych przebiegów
+        if: always()
+        run: docker rm -f swe 2>/dev/null || true
+
+  compile-all:
+    name: Kontrola składni wszystkich warstw
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # Sam kompilator — bez instalowania zależności warstw (w tym AGPL-owego
+      # silnika swisseph, który nie wchodzi do produktu).
+      - name: py_compile
+        run: python -m compileall -q services

.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+
+# Cache warstwy bazodanowej (regenerowalny)
+services/data/.cache/
+*.parquet
+*.db
+
+# Cache efemeryd silnika własnego (pobierane jądra JPL, regenerowalne)
+services/logic/.ephemeris/
+*.bsp
+
+# Dane wejściowe (duże pliki Excela trzymane poza repo)
+services/data/data_files/*.xlsx
+# Rejestr plików (DAN-27) powstaje przy uruchomieniu — to stan, nie kod.
+services/data/data_files/.files-state.json
+!services/data/data_files/.gitkeep
+
+# Narzędzia
+.env
+.DS_Store
+.idea/
+.vscode/

Makefile

@@ -0,0 +1,80 @@
+.PHONY: help install up down sample reindex migrate sql test clean-cache \
+        dev-data dev-logic dev-presentation
+
+# Autodetekcja narzędzia compose: nowe "docker compose" albo stare "docker-compose".
+COMPOSE := $(shell if docker compose version >/dev/null 2>&1; then echo "docker compose"; \
+                   elif command -v docker-compose >/dev/null 2>&1; then echo "docker-compose"; fi)
+
+# Python aktywnego środowiska (venv). Nadpisz: make install PY=python3.12
+PY ?= python
+
+help:
+	@echo "install          - zainstaluj zależności WSZYSTKICH warstw do aktywnego venv"
+	@echo "sample           - wygeneruj przykładowe pliki .xlsx"
+	@echo "dev-data         - uruchom warstwę danych lokalnie (:8002)"
+	@echo "dev-logic        - uruchom warstwę logiczną lokalnie (:8001)"
+	@echo "dev-presentation - uruchom warstwę prezentacji lokalnie (:8000)"
+	@echo "test             - testy warstwy logicznej (silnik efemeryd)"
+	@echo "clean-cache      - wyczyść regenerowalny cache warstwy danych"
+	@echo "reindex          - zbuduj cache + indeks warstwy bazodanowej"
+	@echo "migrate          - ETL: Excel -> SQL"
+	@echo "up / down        - uruchom / zatrzymaj cały stos (Docker; wykryto: $(COMPOSE))"
+	@echo "sql              - Docker z warstwą SQL (DATA_PROVIDER=sql)"
+	@echo ""
+	@echo "Szybki start lokalny (bez Dockera), w 3 terminalach:"
+	@echo "  make install"
+	@echo "  make sample        # opcjonalnie: dane przykładowe"
+	@echo "  make dev-data      # terminal 1"
+	@echo "  make dev-logic     # terminal 2"
+	@echo "  make dev-presentation  # terminal 3  ->  http://localhost:8000"
+
+# --- instalacja zależności do aktywnego środowiska ---
+install:
+	$(PY) -m pip install \
+		-r services/data/requirements.txt \
+		-r services/logic/requirements.txt \
+		-r services/presentation/requirements.txt
+	@echo "OK. Zależności warstw zainstalowane. (Silnik AGPL 'engine-swisseph' instaluje się osobno.)"
+
+sample:
+	cd services/data && $(PY) scripts/make_sample_data.py
+
+reindex:
+	cd services/data && $(PY) -m app.ingest.build_index
+
+migrate:
+	cd services/data && $(PY) -m app.ingest.to_sql
+
+test:
+	cd services/logic && PYTHONPATH=. $(PY) -m pytest tests -q
+
+clean-cache:
+	rm -rf services/data/.cache/* services/logic/.ephemeris/* 2>/dev/null || true
+	@echo "Cache wyczyszczony."
+
+# --- lokalny dev (3 osobne terminale) ---
+dev-data:
+	cd services/data && uvicorn app.main:app --reload --port 8002
+
+dev-logic:
+	cd services/logic && DATA_URL=http://localhost:8002 uvicorn app.main:app --reload --port 8001
+
+dev-presentation:
+	cd services/presentation && LOGIC_URL=http://localhost:8001 uvicorn app.main:app --reload --port 8000
+
+# --- Docker (opcjonalnie) ---
+up:
+	@if [ -z "$(COMPOSE)" ]; then \
+		echo "Nie znaleziono Docker Compose (ani 'docker compose', ani 'docker-compose')."; \
+		echo "Użyj trybu lokalnego: make install, potem dev-data / dev-logic / dev-presentation."; \
+		exit 1; \
+	fi
+	$(COMPOSE) up --build
+
+down:
+	@if [ -z "$(COMPOSE)" ]; then echo "Brak Docker Compose."; exit 1; fi
+	$(COMPOSE) down
+
+sql:
+	@if [ -z "$(COMPOSE)" ]; then echo "Brak Docker Compose."; exit 1; fi
+	DATA_PROVIDER=sql $(COMPOSE) up --build

README.md

@@ -1 +1,76 @@
-# astrololo 
+# astrololo
+
+Aplikacja w **modelu trójwarstwowym**, w pełni modułowa: trzy niezależne usługi,
+każda komunikuje się wyłącznie z sąsiadem (nigdy „przez głowę”).
+
+```
+┌──────────────────────┐   formularz (w dół)   ┌──────────────────────┐   zapytanie (w dół)   ┌──────────────────────┐
+│  PREZENTACJA (:8000) │ ───────────────────▶ │   LOGICZNA (:8001)   │ ───────────────────▶ │  BAZODANOWA (:8002)  │
+│  strona WWW + form   │ ◀─────────────────── │  reguły biznesowe    │ ◀─────────────────── │  wyszukiwanie danych │
+└──────────────────────┘   wyniki (w górę)     └──────────────────────┘   dane (w górę)       └──────────────────────┘
+        HTML/UI                                    pośrednik + logika                         Excel(+cache) ▸ SQL
+```
+
+Każda warstwa to osobny katalog, osobny `requirements.txt`, osobny `Dockerfile`
+i osobne README. Komunikacja przez HTTP/JSON. Warstwa zna **tylko adres warstwy
+bezpośrednio pod nią** — nic o jej wnętrzu.
+
+| Warstwa | Katalog | Zna w dół | Zadanie |
+|--------|---------|-----------|---------|
+| Prezentacji | [`services/presentation`](services/presentation) | `LOGIC_URL` | serwuje stronę, przekazuje formularz, renderuje wyniki |
+| Logiczna | [`services/logic`](services/logic) | `DATA_URL` | reguły biznesowe, tłumaczenie zapytań, opracowanie wyników |
+| Bazodanowa | [`services/data`](services/data) | pliki Excela / SQL | **tylko** wyszukiwanie danych i podanie ich w górę |
+
+## Szybki start (Docker)
+```bash
+make sample      # przykładowe pliki .xlsx do warstwy bazodanowej
+make up          # zbuduj i uruchom 3 warstwy
+# otwórz http://localhost:8000
+```
+
+## Szybki start (lokalnie, bez Dockera — zalecane)
+```bash
+python -m venv .env && source .env/bin/activate   # venv (jednorazowo)
+make install                                       # zależności WSZYSTKICH warstw
+make sample                                        # opcjonalnie: dane przykładowe
+```
+Potem w 3 osobnych terminalach (w każdym `source .env/bin/activate`):
+```bash
+make dev-data            # terminal 1  -> :8002
+make dev-logic           # terminal 2  -> :8001
+make dev-presentation    # terminal 3  -> :8000   ->  http://localhost:8000
+```
+> `make install` instaluje zależności wszystkich trzech warstw do aktywnego venv.
+> Testy silnika: `make test`. Wyczyszczenie cache: `make clean-cache`.
+
+## Modułowość — dowód
+- Wymień prezentację (np. na SPA/React) → reszta bez zmian, kontrakt `/api/query` stały.
+- Wymień bazę (Excel → SQL) → prezentacja i logika bez zmian (patrz niżej).
+- Każdą warstwę da się uruchomić, testować i wdrażać osobno.
+
+## Wydajność warstwy Excela — cache 4-poziomowy
+Dziś dane to setki dużych `.xlsx`, przeszukiwanych po **wykrytym nagłówku** i
+**układzie kolumn**. To kosztowne, więc warstwa bazodanowa ma cache (szczegóły:
+[`services/data/README.md`](services/data/README.md)):
+
+1. **Schemat (L1, SQLite)** — wykryty nagłówek + mapowanie kolumn zapisane raz na wersję pliku.
+2. **Dane (L2, Parquet)** — znormalizowany arkusz; kolejne odczyty 10–100× szybsze niż `.xlsx`.
+3. **Zapytania (L3, in-memory TTL/LRU)** — powtarzalne wyszukiwania natychmiast (łatwo podmienić na Redis).
+4. **Odwrócony indeks (L4, SQLite)** — `wartość → plik`; otwieramy tylko trafione pliki zamiast skanu setek.
+
+Unieważnianie automatyczne: klucz cache = **odcisk pliku** (`mtime+rozmiar`,
+opcjonalnie `sha256`). Zmiana pliku → przebudowa tylko jego wpisów.
+
+## Droga na przyszłość — migracja do SQL
+Warstwa bazodanowa ukrywa źródło za interfejsem `DataProvider` (wzorzec
+Repository). Migracja:
+
+```bash
+make migrate                 # ETL: tym samym loaderem Excel -> tabela 'records' + indeksy
+export DATA_PROVIDER=sql      # przełącz całą warstwę
+```
+
+`SqlDataProvider` realizuje ten sam kontrakt `/search`, więc **warstwa logiczna i
+prezentacji nie zmieniają ani jednej linii**. Odwrócony indeks z L4 (SQLite) jest
+już pomostem — rozbudowa o wszystkie kolumny = docelowa baza.
+# updater test Mon 20 Jul 2026 19:52:08 CEST

docker-compose-stack.yml

@@ -0,0 +1,60 @@
+services:
+  data:
+    image: gitea.czernobog.pl/gitea/astrololo-data:latest
+    container_name: astrololo-data
+    restart: unless-stopped
+    environment:
+      DATA_PROVIDER: ${DATA_PROVIDER:-excel}
+      EXCEL_DIR: /app/data_files
+      CACHE_DIR: /app/.cache
+      INDEXED_KEYS: name,id,symbol
+    volumes:
+      - ./services/data/data_files:/app/data_files
+      - data_cache:/app/.cache
+    # Bez `ports:` CELOWO. Ta usługa rozmawia wyłącznie po sieci wewnętrznej
+    # compose, a opublikowana na hoście była osiągalna z pominięciem logowania
+    # w prezentacji. Do diagnostyki: `docker compose exec` albo tymczasowe
+    # `docker compose run --publish`.
+
+  logic:
+    image: gitea.czernobog.pl/gitea/astrololo-logic:latest
+    container_name: astrololo-logic
+    restart: unless-stopped
+    environment:
+      DATA_URL: http://data:8002
+      EPHEMERIS_ENGINE: own            # silnik własny (permisywny) — domyślny
+      # adres silnika B (AGPL) używany tylko w trybie porównawczym (profil comparison)
+      ENGINE_SWISSEPH_URL: http://engine-swisseph:8003
+    depends_on:
+      - data
+    # Bez `ports:` CELOWO. Ta usługa rozmawia wyłącznie po sieci wewnętrznej
+    # compose, a opublikowana na hoście była osiągalna z pominięciem logowania
+    # w prezentacji. Do diagnostyki: `docker compose exec` albo tymczasowe
+    # `docker compose run --publish`.
+
+  # Silnik B (AGPL) — OPCJONALNY, izolowany. Startuje tylko z profilem "comparison":
+  #   docker compose --profile comparison up
+  # Nie wchodzi do domyślnego (zamkniętego) produktu — patrz services/engine-swisseph/LICENSE.
+  engine-swisseph:
+    image: gitea.czernobog.pl/gitea/astrololo-engine-swisseph:latest
+    container_name: astrololo-engine-swisseph
+    restart: unless-stopped
+    profiles: ["comparison"]
+    # Bez `ports:` CELOWO. Ta usługa rozmawia wyłącznie po sieci wewnętrznej
+    # compose, a opublikowana na hoście była osiągalna z pominięciem logowania
+    # w prezentacji. Do diagnostyki: `docker compose exec` albo tymczasowe
+    # `docker compose run --publish`.
+
+  presentation:
+    image: gitea.czernobog.pl/gitea/astrololo-presentation:latest
+    container_name: astrololo-presentation
+    restart: unless-stopped
+    environment:
+      LOGIC_URL: http://logic:8001
+    depends_on:
+      - logic
+    ports:
+      - "8000:8000"
+
+volumes:
+  data_cache:

docker-compose.yml

@@ -0,0 +1,52 @@
+services:
+  data:
+    build: ./services/data
+    environment:
+      DATA_PROVIDER: ${DATA_PROVIDER:-excel}
+      EXCEL_DIR: /app/data_files
+      CACHE_DIR: /app/.cache
+      INDEXED_KEYS: name,id,symbol
+    volumes:
+      - ./services/data/data_files:/app/data_files
+      - data_cache:/app/.cache
+    # Bez `ports:` CELOWO. Ta usługa rozmawia wyłącznie po sieci wewnętrznej
+    # compose, a opublikowana na hoście była osiągalna z pominięciem logowania
+    # w prezentacji. Do diagnostyki: `docker compose exec` albo tymczasowe
+    # `docker compose run --publish`.
+
+  logic:
+    build: ./services/logic
+    environment:
+      DATA_URL: http://data:8002
+      EPHEMERIS_ENGINE: own            # silnik własny (permisywny) — domyślny
+      # adres silnika B (AGPL) używany tylko w trybie porównawczym (profil comparison)
+      ENGINE_SWISSEPH_URL: http://engine-swisseph:8003
+    depends_on:
+      - data
+    # Bez `ports:` CELOWO. Ta usługa rozmawia wyłącznie po sieci wewnętrznej
+    # compose, a opublikowana na hoście była osiągalna z pominięciem logowania
+    # w prezentacji. Do diagnostyki: `docker compose exec` albo tymczasowe
+    # `docker compose run --publish`.
+
+  # Silnik B (AGPL) — OPCJONALNY, izolowany. Startuje tylko z profilem "comparison":
+  #   docker compose --profile comparison up
+  # Nie wchodzi do domyślnego (zamkniętego) produktu — patrz services/engine-swisseph/LICENSE.
+  engine-swisseph:
+    build: ./services/engine-swisseph
+    profiles: ["comparison"]
+    # Bez `ports:` CELOWO. Ta usługa rozmawia wyłącznie po sieci wewnętrznej
+    # compose, a opublikowana na hoście była osiągalna z pominięciem logowania
+    # w prezentacji. Do diagnostyki: `docker compose exec` albo tymczasowe
+    # `docker compose run --publish`.
+
+  presentation:
+    build: ./services/presentation
+    environment:
+      LOGIC_URL: http://logic:8001
+    depends_on:
+      - logic
+    ports:
+      - "8000:8000"
+
+volumes:
+  data_cache:

docs/canary-registry.md

@@ -0,0 +1,58 @@
+# Rekordy-pułapki (canary) — instrukcja (DAN-26)
+
+Zabezpieczenie **detekcyjne**: nie zapobiega wyciekowi baz, ale pozwala go
+**wykryć** i wskazać **z której kopii** wyciekł. Bazy są kupione i są rdzeniem
+produktu — jeśli krążą gdzie indziej, chcemy to udowodnić.
+
+Mechanizm żyje w warstwie danych (`services/data/app/canary.py`) i działa na
+wyjściu z `/search`, więc pułapki **nie docierają** ani do użytkownika, ani do
+promptu LLM (wymóg LOG-30) — niezależnie od dostawcy (Excel/SQL).
+
+## Jak to działa
+
+1. **Marker** — unikalny ciąg, który nie występuje w realnych danych, wpleciony
+   w kilka wiarygodnie wyglądających rekordów-pułapek w bazach (np. w polu
+   znaczącym: `Ve Tau ASTROLOLO-CANARY-7f3a9`).
+2. **Odsiewanie** — warstwa danych wykrywa rekord z markerem i usuwa go z wyników,
+   zanim opuszczą usługę. Interpretacje i prompty są czyste (log `info`).
+3. **Tripwire** — jeśli zapytanie **celuje wprost** w marker (ktoś enumeruje bazę,
+   a nie liczy horoskopu), leci `warning` — sygnał podejrzanego zachowania.
+
+## Konfiguracja (per wdrożenie)
+
+Zmienne środowiskowe usługi `data`:
+
+| Zmienna | Znaczenie |
+|---|---|
+| `CANARY_MARKERS` | markery oddzielone przecinkami (kilka na wariant) |
+| `CANARY_VARIANT` | etykieta wariantu tego wdrożenia (np. `prod-2026`, `partnerX`) |
+
+Bez `CANARY_MARKERS` mechanizm jest **przezroczysty** (zero kosztu). Markery są
+sekretem — trzymaj je jak `astrololo-auth` (poza repo GitOps), przez `secretKeyRef`.
+
+## Rejestr wariant → kopia (traitor tracing)
+
+Sedno atrybucji: **każda dystrybuowana kopia baz dostaje inny zestaw pułapek**,
+a Ty trzymasz mapę, który wariant trafił dokąd. Gdy zobaczysz pułapkę w cudzej
+kopii → sprawdzasz marker w rejestrze → wiesz, skąd wyciekła.
+
+Rejestr trzymaj **poza kodem i repo** (arkusz/menedżer sekretów po stronie ops),
+np.:
+
+| Wariant | Markery | Wdrożenie / odbiorca | Data |
+|---|---|---|---|
+| `prod-2026` | `…7f3a9`, `…b12c` | produkcja czernobog | 2026-08 |
+| `partnerX` | `…9de4`, `…0a1b` | kopia dla partnera X | 2026-08 |
+
+## Wstrzyknięcie pułapek do baz (krok właściciela)
+
+To robi właściciel na **realnych** plikach (kod tego nie robi — nie ruszamy
+kupionych baz automatycznie): dodać kilka rekordów-pułapek z markerem danego
+wariantu, w stylu nieodróżnialnym od prawdziwych wpisów. Kilka, wtopionych —
+łatwiej, gdy ktoś zna mechanizm, wyciąć jeden oczywisty niż wszystkie.
+
+## Granice
+
+Canary dowodzi pochodzenia tylko, gdy wyciek **zawiera** treść pułapki (pełna
+kopia — tak; parafraza — niekoniecznie). Nie wykrywa retencji *prawdziwej* treści
+u dostawcy LLM — od tego jest bramka LOG-32 i wniosek o Zero Data Retention.

docs/dan25-zabezpieczenie-nfs.md

@@ -0,0 +1,195 @@
+# DAN-25 — zamknięcie dostępu do baz na NFS (TrueNAS SCALE)
+
+Bazy interpretacyjne leżą na `192.168.1.34:/mnt/Tank1/astrololo`. Dziś udział jest
+osiągalny z całej sieci, więc **kto ma dostęp do LAN, bierze kompletne bazy
+w oryginale — z pominięciem logowania, limitów, audytu i canary**. Żadne
+zabezpieczenie w kodzie tego nie zamyka: to najkrótsza droga do wycieku.
+
+Cel: udział `astrololo` widoczny **tylko dla trzech węzłów k3s**, **tylko do
+odczytu**, z **root_squash**.
+
+## ⚠️ Zasada nadrzędna: ruszamy WYŁĄCZNIE udział astrololo
+
+Tank1 obsługuje cały homelab — Proxmox (`proxmox-NFS`), conjurera (`conjurer_swap`,
+z **zapisem**), media, LXC-e, stację roboczą. **Nie dotykamy globalnych ustawień
+usługi NFS ani innych udziałów** — inaczej wywalimy VM-y, bota i bibliotekę mediów.
+Każda komenda niżej celuje w jeden konkretny udział.
+
+Druga zasada: **w TrueNAS SCALE nie edytuje się `/etc/exports` ręcznie.** Plik
+generuje middleware i nadpisze każdą ręczną zmianę. Wszystko robimy przez `midclt`
+(albo GUI: *Shares → Unix (NFS) Shares*).
+
+## Ustalone dane
+
+| Co | Wartość |
+|---|---|
+| NAS | `192.168.1.34` (TrueNAS SCALE / Community Edition) |
+| Udział do zamknięcia | `/mnt/Tank1/astrololo` |
+| Węzły k3s (jedyni uprawnieni) | `192.168.1.73` (server), `192.168.1.80` (agent2), `192.168.1.81` (agent1) |
+| Kto montuje astrololo | wyłącznie pod `data` w ns `astrololo`, **read-only** |
+
+---
+
+## Faza 0 — rozpoznanie (nic nie zmienia)
+
+```bash
+ssh admin@192.168.1.34
+```
+
+Wersja systemu (potwierdza, że komendy niżej pasują):
+
+```bash
+midclt call system.version
+```
+
+Lista udziałów NFS z ich obecnymi ustawieniami — **stąd bierzemy ID udziału astrololo**:
+
+```bash
+midclt call sharing.nfs.query | python3 -m json.tool
+```
+
+> W wyniku poszukaj wpisu ze ścieżką `/mnt/Tank1/astrololo` i zapamiętaj jego `id`.
+> **Sprawdź też, jak nazywają się pola** (`path` vs `paths`, `hosts`, `networks`,
+> `ro`, `maproot_user`, `mapall_user`) — middleware zmieniało ich nazwy między
+> wersjami SCALE. Dalsze komendy używają nazw z Twojego wyniku.
+
+Kto jest teraz podłączony (żeby nie odciąć czegoś w trakcie pracy):
+
+```bash
+ss -tn state established '( sport = :2049 )'
+```
+
+## Faza 1 — dowód dziury (zrób PRZED zmianą)
+
+Na **stacji roboczej** (Mac mini, czyli host spoza klastra):
+
+```bash
+mkdir -p /tmp/nfs-test && sudo mount -t nfs -o ro,vers=3 192.168.1.34:/mnt/Tank1/astrololo /tmp/nfs-test
+```
+
+```bash
+ls -la /tmp/nfs-test | head
+```
+
+Jeśli widzisz pliki baz — **to jest dokładnie problem, który zamykamy**. Odmontuj:
+
+```bash
+sudo umount /tmp/nfs-test
+```
+
+## Faza 2 — kopia obecnej konfiguracji (możliwość cofnięcia)
+
+Na NAS-ie, podstaw `<ID>` z Fazy 0:
+
+```bash
+midclt call sharing.nfs.query '[["id","=",<ID>]]' > /root/astrololo-nfs-share.backup.json && cat /root/astrololo-nfs-share.backup.json
+```
+
+## Faza 3 — zawężenie udziału
+
+Jedna komenda ustawia wszystkie trzy zabezpieczenia naraz: listę hostów, tylko
+odczyt i root_squash. Podstaw `<ID>`:
+
+```bash
+midclt call sharing.nfs.update <ID> '{"hosts": ["192.168.1.73", "192.168.1.80", "192.168.1.81"], "ro": true, "maproot_user": null, "maproot_group": null, "mapall_user": null, "mapall_group": null}'
+```
+
+Co robi każdy element:
+
+| Ustawienie | Znaczenie |
+|---|---|
+| `hosts` | eksport **tylko** dla trzech węzłów k3s — reszta LAN przestaje widzieć udział |
+| `ro: true` | tylko odczyt; aplikacja i tak montuje read-only, więc niczego nie łamie |
+| `maproot_*`, `mapall_*` = `null` | **root_squash**: root z klienta nie jest rootem na udziale |
+
+Zastosuj i sprawdź, że middleware przepisał eksporty:
+
+```bash
+midclt call service.reload nfs && exportfs -v | grep -A1 astrololo
+```
+
+> Jeśli Twoja wersja nie ma `service.reload`, użyj GUI (*Shares → NFS → zapisz*),
+> co wymusi to samo.
+
+## Faza 4 — weryfikacja (wszystkie cztery testy)
+
+**1. Spoza klastra ma NIE działać.** Na Macu:
+
+```bash
+sudo mount -t nfs -o ro,vers=3 192.168.1.34:/mnt/Tank1/astrololo /tmp/nfs-test
+```
+
+Oczekiwane: `access denied` / `Operation not permitted`. **Jeśli montuje się dalej —
+zmiana nie zadziałała, nie idź dalej.**
+
+**2. Z węzła klastra ma działać.**
+
+```bash
+ssh 192.168.1.73 'sudo mount -t nfs -o ro 192.168.1.34:/mnt/Tank1/astrololo /mnt/test && ls /mnt/test | head -3 && sudo umount /mnt/test'
+```
+
+**3. Aplikacja żyje.** Pody muszą wstać i realnie czytać bazy:
+
+```bash
+kubectl -n astrololo rollout restart deploy/data && kubectl -n astrololo rollout status deploy/data
+```
+
+```bash
+kubectl -n astrololo exec deploy/data -- ls /app/data_files | head -3
+```
+
+**4. Reszta homelabu nietknięta** — conjurer (zapis!) i pozostałe udziały:
+
+```bash
+kubectl -n conjurer get pods
+```
+
+```bash
+midclt call sharing.nfs.query | python3 -c "import sys,json;[print(s.get('path') or s.get('paths'), '| hosts:', s.get('hosts'), '| ro:', s.get('ro')) for s in json.load(sys.stdin)]"
+```
+
+Oczekiwane: **tylko** astrololo ma zawężone `hosts` i `ro: true`; reszta bez zmian.
+
+## Faza 5 — wycofanie (gdyby coś padło)
+
+```bash
+midclt call sharing.nfs.update <ID> '{"hosts": [], "ro": false}'
+```
+
+```bash
+midclt call service.reload nfs
+```
+
+To przywraca poprzedni stan (pełna kopia w `/root/astrololo-nfs-share.backup.json`).
+
+---
+
+## Pułapki, o których warto wiedzieć
+
+**Hookscript Proxmoxa.** Na Proxmoxie działa `wait-truenas.sh`, który przed startem
+VM czeka w pętli na `showmount -e 192.168.1.34`. Zawężamy tylko udział astrololo,
+więc `showmount` nadal zwróci pozostałe eksporty i pętla przejdzie. Mimo to sprawdź
+po zmianie:
+
+```bash
+ssh root@pve2 'showmount -e 192.168.1.34'
+```
+
+**Aktualizacja baz przestanie działać przez NFS.** Po `ro: true` nikt nie wgra
+nowych plików baz przez ten udział — również Ty. Do wgrywania użyj GUI TrueNAS,
+SMB albo SSH bezpośrednio na NAS-ie. To celowe: udział ma być drogą tylko do
+czytania przez aplikację.
+
+**`hosts` przyjmuje adresy IP, nie nazwy** — świadomie, żeby dostęp nie zależał od
+DNS-u (AdGuard na `.57`). Gdyby doszedł czwarty węzeł k3s, trzeba dopisać jego IP,
+inaczej pod `data` na nim nie wstanie.
+
+**To nie jest uwierzytelnianie.** Lista IP zatrzymuje przypadkowy i oportunistyczny
+dostęp, ale adres da się podszyć w tej samej sieci. Docelowo (poza zakresem tego
+kroku): NFSv4 + Kerberos albo przeniesienie plików na wolumen nieosiągalny poza
+klastrem — tak mówi samo wymaganie DAN-25.
+
+## Po wykonaniu
+
+Zaktualizuj status DAN-25 w `docs/astrololo_wymagania.xlsx` na **Zrobione** (albo
+**W trakcie**, jeśli zostawiasz Kerberosa jako etap docelowy).

docs/konta-i-audyt.md

@@ -0,0 +1,65 @@
+# Konta imienne i dziennik audytowy (PRE-17)
+
+Zamiast jednego wspólnego hasła: **konta imienne**, bo przy bazach o realnej
+wartości handlowej trzeba wiedzieć **kto** sięgał do treści — i móc odciąć jedną
+osobę bez zmiany hasła całej reszcie.
+
+## Zakładanie konta
+
+Hasło podajesz interaktywnie (nie trafia do historii powłoki ani do listy procesów);
+na wyjściu dostajesz **hash**, nie hasło:
+
+```bash
+cd services/presentation && python scripts/make_user.py alicja
+```
+
+Wynik wklejasz do `APP_USERS` (wpisy po przecinku):
+
+```
+APP_USERS='alicja:scrypt$…,bartek:scrypt$…'
+```
+
+Hash liczy `scrypt` ze stdlib — **bez nowych zależności**. Sekret ustawiasz jak
+resztę (`kubectl create secret …`, `secretKeyRef`), nigdy w repo GitOps.
+
+## Odebranie dostępu jednej osobie
+
+Usuń jej wpis z `APP_USERS` i zrestartuj `presentation`. **Pozostali nie zmieniają
+haseł** — to była główna bolączka wspólnego hasła.
+
+## Uwaga: wspólne hasło przestaje działać
+
+Gdy `APP_USERS` jest ustawione, stare `APP_PASSWORD` **nie działa** (aplikacja
+zgłasza to ostrzeżeniem przy starcie). Celowo: działające obok kont wspólne hasło
+byłoby tylnym wejściem bez śladu w dzienniku, czyli dokładnie problemem, który to
+wymaganie zamyka. Po migracji usuń `APP_PASSWORD` z konfiguracji.
+
+Zgodność wstecz: dopóki `APP_USERS` **nie** jest ustawione, `APP_USER`/`APP_PASSWORD`
+działa jak dotąd — aktualizacja nie wywraca istniejącego wdrożenia.
+
+## Dziennik audytowy
+
+Każde żądanie do chronionej ścieżki zostawia wpis na stdout (w k8s zbierany
+standardowo):
+
+```
+2026-08-03 21:45:44 INFO AUDYT user=alicja ip=10.1.2.3 method=POST path=/interpret status=200 records=428 ms=1530
+```
+
+| Pole | Znaczenie |
+|---|---|
+| `user` | kto (`-` przy nieudanym logowaniu — nie podpowiadamy, które konto istnieje) |
+| `path`, `method`, `status` | co robił i z jakim skutkiem |
+| `records` | **ile rekordów baz** oddaliśmy (`-` gdy żądanie nie dotyka baz) |
+| `ms` | czas obsługi |
+
+`records` jest tu najważniejsze: pojedyncze zapytanie wygląda niewinnie, ale suma
+pokazuje **powolne wypompowywanie bazy** przez osobę uprawnioną — czego żadne
+uwierzytelnienie nie wykryje. Liczone m.in. dla wyszukiwarki sygnifikatorów,
+raportu interpretacji i **eksportu do Excela** (ten wynosi najwięcej naraz).
+
+**W dzienniku nie ma treści** — ani rekordów, ani promptów, ani danych
+urodzeniowych. Logi byłyby kolejnym nośnikiem wycieku; do wykrycia nadużycia
+wystarczą metadane i liczby.
+
+Poziom sterujesz przez `AUDIT_LEVEL` (domyślnie `INFO`).

docs/konta-i-uprawnienia.md

@@ -0,0 +1,168 @@
+# Konta i uprawnienia (PRE-27)
+
+Rozszerzenie kont imiennych z [PRE-17](konta-i-audyt.md): konta zakłada się
+**z aplikacji**, a każde dostaje własny zestaw funkcji.
+
+## Dwie zasady, z których wynika reszta
+
+**1. Konto ograniczone widzi program KOMPLETNY — tylko mniejszy.**
+Nic nie może zdradzać, że istnieje coś więcej. Żadnych wyszarzonych zakładek,
+żadnego „brak uprawnień", żadnego 403 — bo **403 samo w sobie jest informacją**,
+że pod tym adresem coś jest. Ścieżka bez uprawnienia odpowiada **404**, tak samo
+jak adres, którego nie ma.
+
+Z tej zasady wynikło też wyłączenie `/docs`, `/redoc` i `/openapi.json`.
+Automatyczna dokumentacja FastAPI wypisuje komplet tras — czyli spis wszystkich
+funkcji programu. Ochrona zakładek nic by nie dała, gdyby obok leżał ich katalog.
+(Znalezione testem, nie przeglądem kodu.)
+
+**2. Konto administracyjne pochodzi WYŁĄCZNIE ze środowiska.**
+`APP_USER` / `APP_PASSWORD` (albo `APP_USERS`) — jak dotąd. To konto ma wszystkie
+uprawnienia i jako jedyne zarządza pozostałymi. **Nie leży w pliku kont**, więc
+nie da się go skasować ani ograniczyć z ekranu — nawet przez pomyłkę, nawet
+spreparowanym żądaniem. Konto założone w pliku o tym samym loginie **nie
+przesłoni** administracyjnego (kolejność sprawdzania jest odwrotna).
+
+## Podział funkcji
+
+**Ekrany** — zakładki widoczne w nawigacji:
+
+| klucz | zakładka |
+|---|---|
+| `chart` | Horoskop |
+| `interpret` | Interpretacje |
+| `timeline` | Kalendarz |
+| `synastry` | Synastria |
+| `significators` | Sygnifikatory |
+| `compile` | Skompiluj |
+| `settings` | Ustawienia |
+
+**Rozszerzenia** — poziomy złożoności wewnątrz ekranów:
+
+| klucz | co daje |
+|---|---|
+| `houses_compare` | wybór systemu domów, zestawienie kilku obok siebie, obrót koła |
+| `extra_charts` | aspektarian, wykres deklinacji, oś antyscji |
+| `advanced_calc` | stacje planet, tabele żywiołów i faz, aspekty poboczne, zodiaki syderyczne |
+| `ai` | horoskopy pisane przez model językowy (**każde użycie kosztuje**) |
+| `export` | pobieranie PDF i Excela |
+
+Konto bez `houses_compare` dostaje horoskop w Whole Sign i **nie widzi**, że
+systemów jest trzynaście. Konto bez `ai` nie zobaczy przycisku generowania ani
+nie wywoła go z pominięciem interfejsu.
+
+## Gdzie leży granica
+
+W handlerze, nie w szablonie. Ukrycie pola w formularzu chroni przed przypadkiem,
+ale nie przed kimś, kto zna nazwy pól — dlatego `_limit_options()` ścina opcje
+**po stronie serwera**, a rysunki dodatkowe bez uprawnienia w ogóle nie powstają
+(nie ma ich nawet w źródle strony).
+
+Mapa `trasa → uprawnienie` jest **jedna**, w `app/features.py`. Rozproszenie jej
+po dekoratorach kończy się trasą, o której ochronie ktoś zapomniał — a taka dziura
+jest niewidoczna do chwili, gdy ktoś ją znajdzie. Trasa bez wpisu w mapie wymaga
+uprawnień administracyjnych: **przeoczenie ma zamykać, nie otwierać**. Test
+przechodzi po wszystkich trasach aplikacji i wymaga, by każda była opisana.
+
+### Gdy jedna trasa robi kilka rzeczy
+
+Mapa tras nie wystarcza tam, gdzie jedna trasa obsługuje kilka funkcji naraz.
+`POST /interpret` liczy horoskop, ale to samo pole `action` prosi o wygenerowanie
+promptu, napisanie horoskopu przez model albo eksport arkusza. Konto, które ma
+mieć Interpretacje bez generowania, musi dostać tę trasę — więc granica przebiega
+wewnątrz niej, po akcjach: `_AKCJE_POD_UPRAWNIENIEM` przypisuje akcji uprawnienie,
+a `_dozwolona_akcja()` sprowadza żądanie bez uprawnienia do akcji domyślnej ekranu.
+
+Sprowadza — nie odrzuca. Komunikat „brak uprawnień do generowania" sam w sobie
+mówiłby, że taka funkcja istnieje, czyli łamałby zasadę drugą po to, żeby
+wyegzekwować pierwszą. Akcja bez uprawnienia ma wyglądać na literówkę w formularzu.
+
+### Ślad to nie tylko przycisk
+
+Wymaganie brzmi „nie może być śladu", i to jest mocniejsze niż schowanie kontrolki.
+Największym wyciekiem po stronie generowania nie był przycisk, tylko **katalog
+modeli** — nazwy dostawców, nazwy modeli i rozmiary okien kontekstu — wstrzykiwany
+w stronę blokiem JSON na każdym ekranie z generowaniem, niezależnie od uprawnień.
+Dlatego `_llm_catalog_for()` oddaje pusty katalog kontu bez uprawnienia, a szablony
+trzymają pod bramką także znaczniki (`natalNote`, `reportNatal`), pliki skryptów
+(`models.js`, `progress.js`, `natal.js`, `predictions.js`) i **zdania opisujące
+funkcję** — podtytuł ekranu Skompiluj wymieniał interpretację od AI z nazwy.
+
+Testu na to nie da się napisać przez „sprawdź, czy przycisku nie ma": trzeba
+sprawdzić, że w źródle strony nie ma żadnego z tych śladów, i mieć kontrolę
+pozytywną, że przy uprawnieniu wszystkie są. Inaczej test przechodzi także wtedy,
+gdy generowanie jest zepsute dla wszystkich.
+
+## Pełna paranoja: ukrywanie jest nadrzędne
+
+Właściciel produktu postawił to wyżej niż wygodę i wyżej niż czytelność
+komunikatów: *„nie chcę, żeby osoba wrzucająca bazy wiedziała, po co to robi
+i jak będzie w przyszłości działał program, bo to rozgada"*. Persona nazywa się
+**wgrywacz** — konto z uprawnieniami `files` + `files_input` i niczym więcej.
+
+Nie ma dowiedzieć się: jakie inne funkcje istnieją, że teksty pisze model
+językowy i u jakiego dostawcy, do czego służą wgrywane pliki, co jest planowane,
+że istnieje walidacja plików, ani że istnieje konto, które widzi więcej.
+
+### Wyciek prawie nigdy nie siedzi tam, gdzie się go szuka
+
+Audyt sześciu kanałów potwierdził 26 wycieków. Ani jeden nie był przyciskiem.
+
+| Kanał | Co wyciekało |
+|---|---|
+| `/static/**` poza bramką | komplet skryptów i arkuszy dla **niezalogowanego** |
+| komentarze w CSS/JS | pełne zdania po polsku o funkcjach, o kwarantannie i o tym, że administrator widzi więcej |
+| `styles.css` jako jeden plik | nazwy selektorów = spis funkcji programu |
+| `base.html` | skrypty kosmogramu na **każdej** stronie, łącznie z „przyszłą zakładką" |
+| komunikaty błędu | nazwa trasy, nazwa podsystemu, nazwa gałęzi rozwojowej, wewnętrzny `host:port` |
+| komunikat po wgraniu | słowo „administrator" — i **dwie różne treści**, czyli wyrocznia do odgadywania reguł walidacji |
+| `/openapi.json` warstw wewnętrznych | katalog wszystkich funkcji, bez logowania |
+
+### Trzy zasady, które z tego wynikają
+
+**Zasób jest częścią funkcji.** Skrypt i arkusz przechodzą przez tę samą bramkę
+co ekran (`features.STATIC`). Nazwa pliku jest zgadywalna, więc plik publiczny
+opowiada o funkcji równie dokładnie jak przycisk. Publiczny został jeden
+`base.css` — bo potrzebuje go ekran logowania — i dlatego nie wolno w nim
+umieścić niczego, co nazywa funkcję.
+
+**Komentarz nie jedzie na drut.** `_asset_body()` usuwa komentarze przy
+serwowaniu. Zostają w repozytorium, gdzie są potrzebne. Ta jedna zmiana zamyka
+cztery z sześciu kanałów naraz.
+
+**Różnica jest informacją.** Dwa różne komunikaty po wgraniu pliku były
+wyrocznią: wystarczyło wgrywać spreparowane pliki i czytać odpowiedź. Teraz
+komunikat jest jeden, niezależnie od wyniku. Z tego samego powodu odmowa to
+404 identyczne z „nie ma takiej trasy", a akcja bez uprawnienia cofa się do
+domyślnej zamiast tłumaczyć, czego brakuje.
+
+### Zapora słownikowa
+
+Łatanie punkt po punkcie przegrywa z następną zmianą. Dlatego
+`test_slownik_zakazany.py` nie sprawdza miejsc, tylko przechodzi **wszystko**,
+co dane konto może pobrać, i szuka słów, które nie mają prawa paść.
+
+Dwie z trzech list biorą się wprost z katalogu funkcji — nazwa funkcji, adres
+jej ekranu i nazwy jej zasobów — więc dopisanie funkcji automatycznie dopisuje
+je do tego, czego konto bez niej nie może zobaczyć. Trzecia lista, słownictwo
+dziedziny i mechanizmów, jest pisana ręcznie, bo katalog jej nie zna.
+
+Test ma kontrolę pozytywną: dla administratora te same słowa **muszą** się
+pojawiać. Bez niej przechodziłby także wtedy, gdyby program był pusty.
+
+## Gdzie leżą konta
+
+Plik JSON wskazany przez `ACCOUNTS_FILE` (domyślnie `/app/state/accounts.json`),
+na NFS — **własny podkatalog prezentacji**, nie katalog z bazami: zamontowanie
+tutaj całego udziału obeszłoby bokiem zamknięcie dostępu z DAN-25.
+
+Hasła wyłącznie jako hash scrypt, tym samym mechanizmem co `APP_USERS` — jedna
+implementacja, więc nie ma czego rozjechać. Zapis jest **atomowy** (plik
+tymczasowy + `os.replace` w tym samym katalogu): przerwanie zapisu nie obetnie
+pliku, czyli nie skasuje wszystkich kont naraz.
+
+## Czego ten mechanizm NIE robi
+
+Nie zastępuje ochrony baz na poziomie sieci ani NFS (DAN-25). Ktoś z dostępem do
+udziału albo do warstwy danych nadal je odczyta — uprawnienia w aplikacji
+ograniczają to, co widać **przez aplikację**, i tyle.

docs/log33-sekrety-i-rotacja.md

@@ -0,0 +1,171 @@
+# LOG-33 — sekrety w spoczynku i procedura rotacji
+
+Sekrety (`APP_PASSWORD`/`APP_USERS`, `INTERNAL_TOKEN`, klucze łącz AES, klucze API
+do dostawców LLM) trafiają do obiektów Secret w Kubernetesie, gdzie domyślnie są
+**tylko zakodowane base64** — jawne dla każdego, kto przeczyta magazyn stanu k3s
+albo ma prawo odczytu sekretów w namespace.
+
+Ten dokument opisuje: **macierz rotacji** (co restartować przy zmianie czego),
+**procedury rotacji per sekret** i **kroki hartowania**, które wymagają dostępu do
+węzła.
+
+---
+
+## Macierz zależności — kto używa którego sekretu
+
+Wyliczona z żywych deploymentów, nie z założeń:
+
+| Sekret / klucz | Usługi, które go czytają | Restart obejmuje |
+|---|---|---|
+| `astrololo-auth` / **`INTERNAL_TOKEN`** | data, logic, presentation, **render** | **wszystkie cztery, równocześnie** |
+| `astrololo-auth` / `APP_PASSWORD`, `APP_USERS` | presentation | tylko presentation |
+| `astrololo-link` / `LINK_KEY_LOGIC_DATA` | logic, data | **para**: logic + data |
+| `astrololo-link` / `LINK_KEY_PRESENTATION_LOGIC` | presentation, logic | **para**: presentation + logic |
+| `astrololo-link` / `LINK_KEY_PRESENTATION_RENDER` | presentation, render | **para**: presentation + render |
+| `astrololo-llm` / `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | logic | tylko logic |
+
+> **UWAGA — częsty błąd.** Wcześniejsza wersja tego wymagania mówiła o „wszystkich
+> **trzech** usługach" przy `INTERNAL_TOKEN`. To już nieprawda: `render` (PRE-24)
+> również go używa. Restart trzech zostawi render ze starym tokenem i **usługa po
+> cichu przestanie się dogadywać** — dokładnie ta awaria, przed którą wymaganie
+> ostrzega.
+
+Klucze łącz są **parami** — rotacja jednego wymaga restartu tylko dwóch usług, nie
+całej czwórki. W trakcie wymiany para chwilowo się nie dogaduje (klucze muszą być
+zgodne po obu stronach łącza), dlatego restart obu naraz.
+
+---
+
+## Procedury rotacji
+
+### A. Klucze LLM (najbezpieczniejsze do przećwiczenia)
+
+Dotykają wyłącznie logiki, a awaria jest widoczna od razu i nieszkodliwa
+(niedostępna chmura, model lokalny działa dalej). **Zacznij ćwiczenie od tego.**
+
+```bash
+read -rs -p "Nowy ANTHROPIC_API_KEY: " NEW; echo
+```
+
+```bash
+kubectl -n astrololo create secret generic astrololo-llm \
+  --from-literal=OPENAI_API_KEY="$(kubectl -n astrololo get secret astrololo-llm -o jsonpath='{.data.OPENAI_API_KEY}' | base64 -d)" \
+  --from-literal=ANTHROPIC_API_KEY="$NEW" \
+  --dry-run=client -o yaml | kubectl apply -f -
+```
+
+```bash
+unset NEW && kubectl -n astrololo rollout restart deploy/logic && kubectl -n astrololo rollout status deploy/logic
+```
+
+### B. Klucz łącza (para usług)
+
+Przykład dla `LINK_KEY_PRESENTATION_RENDER`. Pozostałe klucze zachowujemy bez zmian,
+odczytując je z istniejącego sekretu — inaczej skasowalibyśmy pozostałe łącza.
+
+```bash
+kubectl -n astrololo create secret generic astrololo-link \
+  --from-literal=LINK_KEY_PRESENTATION_LOGIC="$(kubectl -n astrololo get secret astrololo-link -o jsonpath='{.data.LINK_KEY_PRESENTATION_LOGIC}' | base64 -d)" \
+  --from-literal=LINK_KEY_LOGIC_DATA="$(kubectl -n astrololo get secret astrololo-link -o jsonpath='{.data.LINK_KEY_LOGIC_DATA}' | base64 -d)" \
+  --from-literal=LINK_KEY_PRESENTATION_RENDER="$(openssl rand -hex 32)" \
+  --dry-run=client -o yaml | kubectl apply -f -
+```
+
+```bash
+kubectl -n astrololo rollout restart deploy/presentation deploy/render
+```
+
+```bash
+kubectl -n astrololo rollout status deploy/presentation && kubectl -n astrololo rollout status deploy/render
+```
+
+### C. `INTERNAL_TOKEN` (wszystkie cztery naraz)
+
+Najbardziej wrażliwa rotacja: w trakcie usługi z różnymi tokenami **odrzucają się
+nawzajem**, więc restart musi objąć całą czwórkę.
+
+```bash
+kubectl -n astrololo create secret generic astrololo-auth \
+  --from-literal=APP_PASSWORD="$(kubectl -n astrololo get secret astrololo-auth -o jsonpath='{.data.APP_PASSWORD}' | base64 -d)" \
+  --from-literal=INTERNAL_TOKEN="$(openssl rand -hex 32)" \
+  --dry-run=client -o yaml | kubectl apply -f -
+```
+
+```bash
+kubectl -n astrololo rollout restart deploy/data deploy/logic deploy/presentation deploy/render
+```
+
+```bash
+kubectl -n astrololo rollout status deploy/data && kubectl -n astrololo rollout status deploy/logic && kubectl -n astrololo rollout status deploy/presentation && kubectl -n astrololo rollout status deploy/render
+```
+
+> Jeśli używasz kont imiennych (PRE-17), zamiast `APP_PASSWORD` zachowaj `APP_USERS`
+> — patrz [`konta-i-audyt.md`](konta-i-audyt.md).
+
+### Weryfikacja po KAŻDEJ rotacji
+
+Sam `Running` nie wystarczy — pody wstaną nawet, gdy warstwy się nie dogadują.
+Trzeba sprawdzić **realny przelot przez wszystkie łącza**:
+
+```bash
+kubectl -n astrololo get pods
+```
+
+```bash
+curl -s -o /dev/null -w "aplikacja: %{http_code}\n" -u "<login>:<hasło>" https://astrololo.czernobog.pl/
+```
+
+Policz horoskop w przeglądarce (dotyka presentation→logic→data) i wygeneruj PDF
+(dotyka presentation→render). Dopiero to potwierdza, że wszystkie cztery klucze
+i token są spójne.
+
+---
+
+## Hartowanie — kroki wymagające dostępu do węzła
+
+### 1. Szyfrowanie sekretów w spoczynku (najważniejsze)
+
+k3s z jednym serwerem trzyma stan w **SQLite**, nie w etcd, więc „szyfrowanie etcd"
+sprowadza się do wbudowanej funkcji k3s. Kroki są w sekcji „Co musisz zrobić sam"
+poniżej. Efekt: kopia pliku stanu albo snapshot VM przestaje być wyciekiem haseł
+i kluczy API.
+
+**Granica:** klucz szyfrujący leży na tym samym serwerze. Chroni przed kradzieżą
+pliku/snapshotu — nie przed kimś, kto ma roota na węźle.
+
+### 2. Ograniczenie tokenów kont serwisowych ✅
+
+Zrobione: `automountServiceAccountToken: false` we wszystkich czterech usługach
+(deploy #13). Żadna nie rozmawia z API Kubernetesa — sekrety wstrzykuje kubelet,
+nie pod — więc token był zbędny, a stanowił gotowy punkt wyjścia do klastra.
+
+### 3. RBAC
+
+Stan sprawdzony: **zero RoleBindings** w `astrololo`, `cluster-admin` tylko dla
+`system:masters` i dwóch kont Helma w `kube-system`. Nie ma rozdanych nadmiarowych
+uprawnień do cofania.
+
+Realna ekspozycja to **kubeconfig admina**. Sensowny krok: osobny, ograniczony
+kubeconfig do codziennej pracy, a admin tylko wtedy, gdy naprawdę potrzebny.
+
+### 4. Sealed Secrets / SOPS — świadomie ODŁOŻONE
+
+Dziś sekrety tworzone są ręcznie i **nie ma ich w repo GitOps** — czyli zasada
+„nie wpisywać sekretów do repozytorium" **jest już spełniona**. Kosztem jest
+odtwarzalność: po utracie klastra nikt nie wie, co tam było.
+
+Sealed Secrets pozwoliłoby trzymać je w gicie w postaci zaszyfrowanej, ale to
+zmiana filozofii i **nowy pojedynczy punkt awarii**: utrata klucza kontrolera =
+utrata wszystkich sekretów. Rekomendacja: dopiero po punkcie 1, i tylko jeśli
+zależy Ci na odtwarzalności klastra z gita.
+
+---
+
+## Czego NIE robimy
+
+- **Nie wpisujemy sekretów do logów.** Dziennik audytowy (PRE-17) niesie wyłącznie
+  metadane i liczby.
+- **Nie wpisujemy sekretów do repo GitOps.** Manifesty odwołują się do sekretów
+  przez `secretKeyRef` i celowo nie zawierają wartości.
+- **Nie zostawiamy haseł w historii powłoki** — stąd `read -rs` i odczyt istniejących
+  wartości przez `kubectl … | base64 -d` zamiast wpisywania ich ponownie.

docs/wdrozenie-pre16.md

@@ -0,0 +1,296 @@
+# Wdrożenie PRE-16 — HTTPS na wejściu i szyfrowanie łączy między warstwami
+
+Instrukcja krok po kroku. **Kolejność ma znaczenie** — punkt „Dlaczego taka
+kolejność" niżej tłumaczy, co się stanie, jeśli ją zamienić.
+
+Dotyczy dwóch pull requestów:
+
+| Repo | PR | Co wnosi |
+|---|---|---|
+| `gitea/astrololo` | [#21](https://gitea.czernobog.pl/gitea/astrololo/pulls/21) | kod: szyfrowanie łączy, limit żądań za proxy |
+| `gitea/deploy` | [#4](https://gitea.czernobog.pl/gitea/deploy/pulls/4) | manifesty: Ingress, certyfikat, klucze łączy |
+
+---
+
+## Co się właściwie zmienia
+
+**Na wejściu do aplikacji.** Dotąd logowanie szło przez HTTP Basic po zwykłym
+http — czyli hasło leciało siecią w postaci trywialnej do podsłuchania (base64 to
+nie szyfrowanie). Po zmianie wejście jest po https, a http odsyła na https.
+Przy okazji **odblokowują się dwie funkcje zepsute dziś z tego samego powodu**:
+geolokalizacja („Tu i teraz") i kopiowanie promptu do schowka działają wyłącznie
+w tzw. secure context i po http po prostu odmawiały.
+
+**Między warstwami.** Prezentacja, logika i dane rozmawiały ze sobą otwartym
+tekstem wewnątrz klastra. Token międzywarstwowy mówił *kto* pyta, ale nie ukrywał
+*czego dotyczy odpowiedź* — a płyną nią surowe wiersze oryginalnych baz. Teraz
+każde ciało żądania i odpowiedzi jest szyfrowane **AES-256-GCM**, osobnym kluczem
+na każdą parę rozmówców.
+
+**Wejście na świat pozostaje jedno: prompt do modelu.** Ta zmiana niczego tu nie
+rusza — dotyczy wyłącznie ruchu wewnątrz sieci i wejścia z przeglądarki.
+
+---
+
+## Zanim zaczniesz — stan wyjściowy
+
+```bash
+kubectl -n astrololo get deploy,svc
+kubectl -n astrololo get secret                 # powinny być: astrololo-auth, gitea-registry
+kubectl -n kube-system get svc traefik -o jsonpath='{.status.loadBalancer.ingress[*].ip}'; echo
+```
+
+Zanotuj adres Traefika — będzie potrzebny w kroku 3. Sprawdź też, czy działa
+aplikacja w obecnej postaci (przez NodePort), żeby mieć punkt odniesienia.
+
+---
+
+## Krok 1 — sekret z kluczami łączy
+
+**Przed czymkolwiek innym.** Klucze muszą istnieć, zanim pody spróbują wstać
+z nową konfiguracją, bo bez nich celowo **nie wystartują**.
+
+```bash
+kubectl -n astrololo create secret generic astrololo-link \
+  --from-literal=LINK_KEY_PRESENTATION_LOGIC="$(openssl rand -hex 32)" \
+  --from-literal=LINK_KEY_LOGIC_DATA="$(openssl rand -hex 32)"
+```
+
+Kluczy nikt nigdy nie musi oglądać — służą tylko usługom. Nie ma ich w repo
+GitOps i **nie ma ich tam wkładać**: cokolwiek trafi do gita, zostaje w historii
+na zawsze.
+
+Dwa osobne klucze to nie ozdobnik. Przejęcie klucza prezentacji nie daje dostępu
+do warstwy danych, gdzie leżą całe bazy. Logika dostaje oba, bo rozmawia w obie
+strony; prezentacja i dane dostają wyłącznie swój.
+
+Sprawdź:
+```bash
+kubectl -n astrololo get secret astrololo-link -o jsonpath='{.data}' | tr ',' '\n'
+# oczekiwane: dwa klucze, każdy 64 znaki po odkodowaniu (32 bajty)
+```
+
+---
+
+## Krok 2 — cert-manager
+
+Jednorazowo, na cały klaster:
+
+```bash
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.0/cert-manager.yaml
+kubectl -n cert-manager rollout status deploy/cert-manager deploy/cert-manager-webhook --timeout=180s
+```
+
+Poczekaj, aż **webhook** będzie gotowy — dopóki nie wstanie, tworzenie obiektów
+`Certificate` kończy się błędem połączenia i wygląda jak zepsuty manifest.
+
+Sprawdź:
+```bash
+kubectl get crd | grep cert-manager | head -3     # muszą się pojawić
+```
+
+> **Dlaczego własne CA, a nie Let's Encrypt.** Klaster stoi w LAN (Traefik trzyma
+> LoadBalancera na adresach 192.168.1.x), więc walidacja HTTP-01 nie ma jak dojść
+> z internetu, a DNS-01 wymagałby trzymania w klastrze tokena API do domeny.
+> Własne CA nie potrzebuje niczego z zewnątrz i odnawia certyfikaty samo. Cena:
+> raz na urządzenie importujesz korzeń (krok 6).
+
+---
+
+## Krok 3 — DNS
+
+Wpis `astrololo.czernobog.pl` → adres Traefika z kroku „stan wyjściowy”.
+W routerze, lokalnym DNS-ie albo doraźnie w `/etc/hosts`:
+
+```bash
+echo "192.168.1.73  astrololo.czernobog.pl" | sudo tee -a /etc/hosts
+```
+
+**To nie jest krok opcjonalny.** Service `presentation` przestaje być NodePortem
+(był drugą, nieszyfrowaną drogą do aplikacji — czyli obejściem całego PRE-16),
+więc po wdrożeniu manifestów nazwa jest jedynym wejściem. Awaryjnie zawsze zostaje:
+
+```bash
+kubectl -n astrololo port-forward svc/presentation 8000:8000   # http://localhost:8000
+```
+
+---
+
+## Krok 4 — merge PR-a aplikacji (astrololo #21)
+
+Teraz, **przed** manifestami.
+
+```bash
+tea pr merge --login gitea --repo gitea/astrololo 21
+```
+
+Po merge'u CI zbuduje obrazy, a image-updater sam podbije tagi w repo `deploy`,
+skąd ArgoCD wymieni pody. Poczekaj, aż to się przetoczy:
+
+```bash
+kubectl -n astrololo rollout status deploy/presentation deploy/logic deploy/data
+kubectl -n astrololo get pods -o jsonpath='{range .items[*]}{.spec.containers[0].image}{"\n"}{end}'
+```
+
+Na tym etapie **nic się jeszcze nie szyfruje** — nowy kod to potrafi, ale zmienne
+z kluczami dokłada dopiero PR do `deploy`. Aplikacja działa dokładnie jak dotąd.
+To celowe: chcemy, żeby *cała* obsada podów umiała szyfrować, zanim ktokolwiek
+tego zażąda.
+
+---
+
+## Krok 5 — merge PR-a manifestów (deploy #4)
+
+```bash
+tea pr merge --login gitea --repo gitea/deploy 4
+```
+
+ArgoCD zsynchronizuje się sam (`automated`, `selfHeal`). Wjeżdża naraz: Ingress,
+certyfikat, zmienne z kluczami, `TRUST_PROXY` i zdjęcie NodePortu.
+
+```bash
+kubectl -n argocd get application astrololo
+kubectl -n astrololo rollout status deploy/presentation deploy/logic deploy/data
+kubectl -n astrololo get certificate      # astrololo-ca i astrololo-tls: READY=True
+```
+
+> **Spodziewaj się kilkudziesięciu sekund błędów w trakcie.** Pody wymieniają się
+> po kolei, więc przez chwilę stara prezentacja (jeszcze bez klucza) rozmawia
+> z nową logiką (już z kluczem) i dostaje odmowę. To zamierzone: alternatywą byłby
+> tryb „przyjmuj i szyfrowane, i jawne”, który zwykle zostaje włączony na zawsze.
+
+Merge nie cofnie tagów obrazów — PR dotyka w `kustomization.yaml` wyłącznie listy
+`resources`, nie bloku `images`, więc git złoży to z nowszymi tagami z mastera.
+
+---
+
+## Krok 6 — zaufanie do własnego CA (raz na urządzenie)
+
+Bez tego przeglądarka pokaże ostrzeżenie o certyfikacie. Korzeń jest ważny 10 lat,
+więc robisz to raz:
+
+```bash
+kubectl -n astrololo get secret astrololo-ca -o jsonpath='{.data.ca\.crt}' \
+  | base64 -d > astrololo-ca.crt
+
+# macOS — do systemowego zaufania (poprosi o hasło administratora)
+sudo security add-trusted-cert -d -r trustRoot \
+  -k /Library/Keychains/System.keychain astrololo-ca.crt
+
+# Linux (Debian/Ubuntu)
+sudo cp astrololo-ca.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates
+```
+
+Firefox ma **własny** magazyn certyfikatów — import przez *Ustawienia →
+Prywatność i bezpieczeństwo → Wyświetl certyfikaty → Organy certyfikacji*.
+
+---
+
+## Krok 7 — sprawdzenie, że działa to, co miało zadziałać
+
+### Wejście po https
+```bash
+curl -sI http://astrololo.czernobog.pl/ | head -2          # 301 → https
+curl -s -o /dev/null -w "bez hasła: %{http_code}\n"  https://astrololo.czernobog.pl/
+curl -s -o /dev/null -w "z hasłem: %{http_code}\n" -u astrololo:'<hasło>' https://astrololo.czernobog.pl/
+curl -sI -u astrololo:'<hasło>' https://astrololo.czernobog.pl/ | grep -i strict-transport
+```
+Oczekiwane: **301**, **401**, **200**, nagłówek HSTS obecny. Brak ostrzeżenia
+o certyfikacie w przeglądarce oznacza, że krok 6 się udał.
+
+### W przeglądarce
+Kliknij **„Tu i teraz"** — powinno pobrać lokalizację (po http odmawiało).
+Wygeneruj prompt i kliknij **kopiuj** — schowek powinien zadziałać bez obejść.
+
+### Szyfrowanie łączy — sprawdzenie wprost
+Najmocniejszy test to próba obejścia. Z wnętrza klastra, **bez klucza**:
+
+```bash
+kubectl -n astrololo exec deploy/presentation -- \
+  python -c "
+import httpx, os
+r = httpx.post('http://logic:8001/chart/report',
+               json={'when_utc':'1984-04-30T09:20:00+00:00','lat':50.06,'lon':19.94},
+               headers={'X-Astrololo-Token': os.environ['INTERNAL_TOKEN']})
+print(r.status_code, r.text[:120])
+"
+```
+Oczekiwane: **400** i `Łącze międzywarstwowe wymaga szyfrowania.` Zwróć uwagę, że
+żądanie miało **prawidłowy token** — sam token już nie wystarcza, i o to chodziło.
+
+To samo w dół, do warstwy danych:
+```bash
+kubectl -n astrololo exec deploy/logic -- \
+  python -c "
+import httpx, os
+r = httpx.post('http://data:8002/search',
+               json={'key':'significator','value':'[Sat','exact':False,'limit':5},
+               headers={'X-Astrololo-Token': os.environ['INTERNAL_TOKEN']})
+print(r.status_code, r.text[:120])
+"
+```
+
+### Logi startowe
+```bash
+kubectl -n astrololo logs deploy/logic | grep -i "łącze\|UWAGA"
+```
+Powinno być `łącze szyfrowane (AES-256-GCM…)`. Jeśli widzisz ostrzeżenie
+o rozmowie **jawnym tekstem** — klucz nie doszedł do poda.
+
+---
+
+## Dlaczego taka kolejność
+
+| Kolejność | Skutek zamiany |
+|---|---|
+| Sekret **przed** manifestami | `LINK_ENCRYPTION_REQUIRED=true` bez klucza celowo wywraca start. Pody wpadną w CrashLoop i będą tak siedzieć do czasu utworzenia sekretu. |
+| cert-manager **przed** manifestami | API odrzuci `Certificate`/`Issuer` jako nieznane rodzaje zasobów, ArgoCD pokaże aplikację jako niezsynchronizowaną i sam tego nie naprawi. |
+| DNS **przed** manifestami | NodePort znika razem z nimi. Bez wpisu DNS zostaje tylko `port-forward`. |
+| Aplikacja **przed** manifestami | Odwrotnie: manifesty włączyłyby szyfrowanie na obrazach, które go nie znają — wszystkie żądania kończyłyby się odmową do czasu przebudowy obrazów. |
+
+Fail-closed w obie strony jest zamierzony. Usługa, która wstała i **po cichu nie
+szyfruje**, jest gorsza niż pod w CrashLoop — awarii nie widać, a bazy jadą
+otwartym tekstem.
+
+---
+
+## Wycofanie
+
+Manifestów: `git revert` merge'a w `deploy` — ArgoCD samo wróci do NodePortu
+i ruchu bez szyfrowania. Kod aplikacji **nie wymaga wycofania**: bez zmiennych
+`LINK_KEY_*` moduł przepuszcza ruch jak dotąd (i głośno o tym mówi w logach).
+
+Certyfikat i CA zostają w namespace; usunięcie: `kubectl -n astrololo delete
+certificate astrololo-ca astrololo-tls`. cert-managera można zostawić — nie
+przeszkadza.
+
+---
+
+## Gdy coś nie gra
+
+| Objaw | Przyczyna | Co zrobić |
+|---|---|---|
+| Pody w `CrashLoopBackOff`, w logach `LINK_ENCRYPTION_REQUIRED … nie ustawiony` | brak sekretu `astrololo-link` | krok 1, potem `rollout restart` |
+| `400 Łącze międzywarstwowe wymaga szyfrowania` przy normalnym korzystaniu | jedna warstwa ma klucz, druga nie (albo trwa rollout) | `rollout status`; sprawdź, czy wszystkie trzy pody mają zmienną |
+| `400 Nie udało się odczytać zaszyfrowanego żądania` | klucze po obu stronach łącza są **różne** | wymień sekret i zrestartuj **wszystkie trzy** naraz |
+| `Certificate` stoi w `READY=False` | webhook cert-managera jeszcze nie wstał | `kubectl -n cert-manager get pods`, poczekaj i sprawdź `kubectl -n astrololo describe certificate astrololo-tls` |
+| Przeglądarka: „połączenie nie jest prywatne” | korzeń CA nieimportowany na tym urządzeniu | krok 6 (pamiętaj, że Firefox ma osobny magazyn) |
+| `404` z Traefika pod adresem aplikacji | DNS wskazuje gdzie indziej niż LoadBalancer Traefika | porównaj `dig +short astrololo.czernobog.pl` z adresem z kroku „stan wyjściowy” |
+| Limit żądań odcina wszystkich naraz | brak `TRUST_PROXY=true` — cały ruch liczony jako jeden klient | sprawdź zmienną w `deploy/presentation` |
+
+---
+
+## Czego to nie załatwia
+
+- **Szyfrowane są ciała żądań, nie nagłówki.** Ścieżka (`/search`) i token
+  międzywarstwowy jadą czytelnie. Sam token nikomu nic nie daje — bez klucza łącza
+  każde żądanie kończy się odmową — ale metadanych to nie ukrywa. Pełne ukrycie
+  wymagałoby mTLS.
+- **Własne CA to nie publiczne zaufanie.** Każde nowe urządzenie wymaga importu
+  korzenia. Gdyby aplikacja miała kiedyś wyjść na świat, właściwą drogą jest
+  Let's Encrypt przez DNS-01.
+- **NFS z plikami baz** stoi obok aplikacji — kto ma dostęp do share'u, bierze
+  pliki z pominięciem wszystkich powyższych zabezpieczeń. Do zamknięcia po stronie
+  infrastruktury (eksport tylko dla IP węzłów, `root_squash`, najlepiej read-only).
+- **Sekrety w etcd** są tylko zakodowane base64. Docelowo: szyfrowanie etcd
+  at-rest albo Sealed Secrets / SOPS.

docs/wdrozenie-render-pdf.md

@@ -0,0 +1,139 @@
+# Wdrożenie usługi `render` — raport PDF (PRE-24)
+
+Instrukcja krok po kroku dla nowego komponentu. Dotyczy dwóch repozytoriów:
+
+| Repo | Co wnosi |
+|---|---|
+| `gitea/astrololo` | usługa `services/render`, klient w prezentacji, przycisk „Pobierz PDF", wariant kosmogramu do druku |
+| `gitea/deploy` | `astrololo/render.yaml`, adres i klucz łącza w `presentation.yaml` |
+
+---
+
+## Dlaczego osobna usługa
+
+TeX Live waży setki megabajtów. W obrazie prezentacji spowalniałby każdy build
+i deploy, a przy każdej poprawce w CSS trzeba by go ciągnąć od nowa. Osobno:
+obraz produktu zostaje mały, TeX aktualizuje się niezależnie, a **awaria renderu
+nie kładzie aplikacji** — przestaje działać wyłącznie przycisk „Pobierz PDF".
+
+To ta sama zasada, co przy izolacji silnika swisseph (LOG-27).
+
+---
+
+## Krok 1 — klucz łącza (PRZED wdrożeniem)
+
+Usługa dostaje **cały raport**: dane urodzeniowe i opisy z baz. Łącze jest
+szyfrowane AES-256-GCM, własnym, **trzecim** kluczem — przejęcie go nie może
+otwierać łącza do logiki ani do danych.
+
+Sekret `astrololo-link` już istnieje (PRE-16); dokładamy do niego trzeci klucz,
+**zachowując dwa dotychczasowe**:
+
+```bash
+kubectl -n astrololo create secret generic astrololo-link \
+  --from-literal=LINK_KEY_PRESENTATION_LOGIC="$(kubectl -n astrololo get secret astrololo-link \
+      -o jsonpath='{.data.LINK_KEY_PRESENTATION_LOGIC}' | base64 -d)" \
+  --from-literal=LINK_KEY_LOGIC_DATA="$(kubectl -n astrololo get secret astrololo-link \
+      -o jsonpath='{.data.LINK_KEY_LOGIC_DATA}' | base64 -d)" \
+  --from-literal=LINK_KEY_PRESENTATION_RENDER="$(openssl rand -hex 32)" \
+  --dry-run=client -o yaml | kubectl apply -f -
+```
+
+Sprawdzenie — mają być **trzy** klucze:
+```bash
+kubectl -n astrololo get secret astrololo-link -o jsonpath='{.data}' | tr ',' '\n'
+```
+
+> **Uwaga:** `LINK_ENCRYPTION_REQUIRED=true` działa fail-closed. Bez klucza pod
+> `render` **nie wstanie** — i tak ma być. Usługa, która wstała i po cichu nie
+> szyfruje, jest gorsza niż CrashLoop, bo awarii nie widać.
+
+---
+
+## Krok 2 — obraz usługi
+
+Obraz budowany jest osobnym workflow (jak silnik swisseph — nie wchodzi do
+głównego pipeline'u produktu). Pierwszy build trwa dłużej, bo ciągnie TeX Live.
+
+```bash
+kubectl -n astrololo get deploy render -o jsonpath='{.spec.template.spec.containers[0].image}'; echo
+```
+
+Pakiety w obrazie dobrane **wąsko** (nie `texlive-full`, który ma kilka GB):
+
+| Pakiet | Po co |
+|---|---|
+| `texlive-xetex` | silnik **XeLaTeX** — konieczny, bo raport ma polskie znaki i glify astrologiczne; `pdflatex` ich nie złoży |
+| `texlive-latex-recommended` | `geometry`, `graphicx` |
+| `fonts-dejavu-core` | jeden font na polskie znaki **i** symbole (♄ ♓ ☉) |
+| `librsvg2-bin` | `rsvg-convert` — SVG kosmogramu → PDF (LaTeX nie wstawia SVG wprost) |
+
+Dockerfile sprawdza obecność obu narzędzi **przy budowie**, więc zepsuty obraz
+nie dojedzie na produkcję niezauważony.
+
+---
+
+## Krok 3 — merge manifestów
+
+```bash
+tea pr merge --login gitea --repo gitea/deploy <numer>
+kubectl -n astrololo rollout status deploy/render deploy/presentation
+```
+
+Wjeżdża naraz: `Deployment` + `Service` renderu (ClusterIP — **bez** Ingressu
+i NodePortu, nie ma powodu sięgać do niej z zewnątrz) oraz `RENDER_URL`
+i trzeci klucz w prezentacji.
+
+---
+
+## Krok 4 — sprawdzenie
+
+### Narzędzia są na miejscu
+`/health` raportuje obecność `xelatex` i `rsvg-convert`, żeby zepsuty obraz
+było widać od razu, a nie dopiero przy pierwszym raporcie:
+
+```bash
+kubectl -n astrololo exec deploy/presentation -- \
+  python -c "import httpx; print(httpx.get('http://render:8004/health').text)"
+```
+Oczekiwane: `{"status":"ok","layer":"render","tools":{"xelatex":true,"rsvg-convert":true}}`.
+Gdy `status` to `degraded` — obraz zbudował się bez któregoś narzędzia.
+
+### Łącze faktycznie szyfruje
+Najmocniejszy test to próba obejścia. Z wnętrza klastra, **z poprawnym tokenem,
+ale bez szyfrowania**:
+
+```bash
+kubectl -n astrololo exec deploy/presentation -- python -c "
+import httpx, os
+r = httpx.post('http://render:8004/pdf', json={'person':'test'},
+               headers={'X-Astrololo-Token': os.environ['INTERNAL_TOKEN']})
+print(r.status_code, r.text[:80])
+"
+```
+Oczekiwane: **400** i `Łącze międzywarstwowe wymaga szyfrowania.` Sam token już
+nie wystarcza — o to chodziło.
+
+### Raport od końca do końca
+W przeglądarce: **Skompiluj** → wypełnij dane → *Złóż podsumowanie* → *Pobierz PDF*.
+PDF ma zacząć się od imienia i nazwiska, potem wprowadzone dane, **rysunek
+kosmogramu**, a po nim interpretacja natalna i predykcje okresowe.
+
+---
+
+## Czego ta wersja nie załatwia
+
+- **Kompilacja PDF nie została sprawdzona end-to-end** w środowisku, w którym
+  powstawała — nie było tam ani TeX Live, ani runtime'u kontenerów. Sprawdzone
+  jest wszystko dookoła: generowanie źródła `.tex` (w tym ucieczka znaków
+  specjalnych), szyfrowanie łącza, kontrakt API i samowystarczalność SVG.
+  **Pierwsze uruchomienie na klastrze trzeba obejrzeć.**
+- **Dzielenie wyrazów** jest angielskie — nie wciągamy `polyglossia`, żeby nie
+  puchł obraz. Tekst składa się poprawnie, tylko przenoszenie bywa nieoptymalne.
+- **Brak kolejki**. Długi raport blokuje jedno połączenie na czas kompilacji
+  (timeout klienta: 180 s). Przy większym ruchu warto dołożyć zadania w tle.
+- **Glify w tekście od modelu**. Kosmogram idzie jako obraz (rysuje go
+  `rsvg-convert` z DejaVu), ale gdyby model wplótł symbole w prozę, złoży je
+  XeLaTeX — też z DejaVu. Jeśli któregoś zabraknie, LaTeX zgłasza
+  „Missing character" w logu i **nie drukuje znaku**; warto zerknąć w log
+  pierwszego raportu.

services/astrodemo/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Do obrazu wchodzi WYŁĄCZNIE kod aplikacji. `COPY . .` wnosiło też katalog
+# tests/ — a leży w nim lista słów, które w tej usłudze nie mają prawa paść,
+# wypisanych wprost. Obraz tej usługi się KOMUŚ ODDAJE, więc niósłby dokładnie
+# to, co ten test ma pilnować. Przy okazji obraz jest mniejszy.
+COPY app ./app
+
+EXPOSE 8005
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8005"]

services/astrodemo/README.md

@@ -0,0 +1,91 @@
+# astrodemo — wersja demonstracyjna (PRE-28)
+
+Osobna warstwa prezentacji o **dwóch funkcjach**:
+
+1. **dodanie pliku bazy** — wgranie i włączenie do użytku jedną czynnością,
+2. **zapytanie o interpretację urodzeniową** dla podanych danych wejściowych.
+
+I na tym koniec. Nie ma tu kosmogramu, synastrii, kalendarza, promptów do modelu,
+eksportu ani kont — nie są ukryte, tylko **nie istnieją w tym obrazie**.
+
+## Dlaczego osobna usługa, a nie konto z ograniczeniami
+
+Mechanizm uprawnień z PRE-27 umiałby to ukryć w pełnej aplikacji. Ale **ukrycie
+a nieobecność to dwie różne rzeczy**: tutaj nie ma tras, nie ma szablonów, nie ma
+nawet metod w kliencie warstwy logicznej. Demo można komuś oddać, nie oddając przy
+okazji kodu reszty programu.
+
+## Izolacja: własne dane, pula na konto
+
+```
+astrodemo  →  logic-demo  →  data-demo  →  udział astrololo-demo (pusty na starcie)
+                                              └── klientA/   ← pula konta
+                                              └── klientB/   ← pula konta
+```
+
+**Oryginalne bazy interpretacyjne są dla demo nieosiągalne.** Nie chodzi
+o uprawnienia: demo ma własną warstwę danych, pracującą na osobnym udziale.
+Osobna jest też warstwa logiczna, bo zna ona JEDEN adres warstwy danych — demo
+korzystające z produkcyjnej logiki i tak trafiłoby na produkcyjne bazy.
+
+**Każde konto ma własną pulę** plików: swój podkatalog na tym udziale. Konta nie
+widzą swoich baz nawzajem ani w liście, ani w wynikach wyszukiwania. Dlatego demo
+można rozdawać szeroko.
+
+Pula bierze się **z loginu zalogowanej osoby** i z niczego innego. Gdyby
+przychodziła z żądania, wystarczyłoby podstawić cudzy login, żeby czytać cudze
+bazy — osobny test wysyła `tenant`, `user` i `login` w formularzu i sprawdza, że
+nie mają na nią wpływu.
+
+Nazwa puli przechodzi przez sito dopuszczające wyłącznie znaki bezpieczne
+w nazwie katalogu: `../..` czy ukośnik wyprowadziłyby zapytanie poza udział.
+
+**Pula klienta to jeden katalog**, więc przejście na pełną wersję nie oznacza
+utraty wgrań — procedura importu jest w runbooku wdrożenia (repo `deploy`,
+`astrololo/README-astrodemo.md`).
+
+## Konfiguracja
+
+| zmienna | znaczenie |
+|---|---|
+| `LOGIC_URL` | adres warstwy logicznej (domyślnie `http://localhost:8001`) |
+| `ASTRODEMO_USERS` | konta jako `login:sekret`, po przecinku. Sekret jawny albo hash `scrypt$sól$hash`. Każdy login = osobna pula plików |
+| `ASTRODEMO_USER` / `ASTRODEMO_PASSWORD` | pojedyncze konto — zgodność wstecz, działa gdy `ASTRODEMO_USERS` jest puste. **Brak obu = aplikacja stoi otwarta** i mówi o tym głośno przy starcie |
+| `INTERNAL_TOKEN` | token międzywarstwowy (LOG-32) — ten sam co reszta usług |
+| `LINK_KEY_PRESENTATION_LOGIC` | klucz szyfrowanego łącza (PRE-16) — ten sam co prezentacja |
+| `RATE_LIMIT_PER_MIN` | limit żądań na adres, domyślnie 60; `0` wyłącza |
+| `REPORT_LIMIT` | górny limit rekordów w jednej odpowiedzi, domyślnie 2000 |
+| `TRUST_PROXY` | `true` za Ingressem — inaczej limit liczy wszystkich do jednego wiadra |
+
+Hash hasła zrobisz tym samym skryptem, co dla głównej aplikacji:
+
+```bash
+cd services/presentation && python scripts/make_user.py demo
+```
+
+## Uruchomienie lokalne
+
+```bash
+cd services/astrodemo
+pip install -r requirements-dev.txt
+ASTRODEMO_PASSWORD=tajne LOGIC_URL=http://localhost:8001 \
+  uvicorn app.main:app --port 8005
+```
+
+Testy:
+
+```bash
+cd services/astrodemo && PYTHONPATH=. pytest tests -q
+```
+
+## Co pilnują testy
+
+Poza zwykłą poprawnością — dwie własności, które łatwo zepsuć bez zauważenia:
+
+* **powierzchnia**: zbiór tras aplikacji musi być dokładnie taki, jak dwie funkcje
+  wymagają; klient warstwy logicznej ma tylko te metody, których używa. Trasa,
+  o której nikt nie pamiętał, jest tu realnym ryzykiem, bo ta usługa rozmawia
+  z produkcyjną warstwą danych.
+* **milczenie o regułach walidacji**: plik odrzucony daje komunikat bez powodu.
+  Reguły zna wyłącznie administrator w pełnej aplikacji (DAN-27), a demo nie ma
+  prawa ich zdradzić nawet mimochodem.

services/astrodemo/app/clients/logic_client.py

@@ -0,0 +1,79 @@
+"""Klient warstwy logicznej — CELOWO okrojony do dwóch funkcji (PRE-28).
+
+Ma tu być wyłącznie to, czego ta usługa naprawdę używa. Metoda, której nie ma,
+nie zostanie przypadkiem zawołana ani nie podpowie, że po drugiej stronie jest
+coś więcej.
+
+Rozmowa idzie tym samym szyfrowanym łączem co reszta (PRE-16) i pod tym samym
+tokenem międzywarstwowym (LOG-32) — demo nie jest furtką omijającą ochronę.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from app import link_crypto
+from app.config import settings
+
+
+def _auth_headers() -> dict[str, str]:
+    token = os.getenv("INTERNAL_TOKEN", "")
+    return {"X-Astrololo-Token": token} if token else {}
+
+
+def _link() -> link_crypto.Link | None:
+    """Klucz łącza czytany przy KAŻDYM wywołaniu — pod przeżywa rotację sekretu
+    bez restartu, a brak klucza przy wymaganym szyfrowaniu ma zatrzymać żądanie
+    ZANIM cokolwiek wyjdzie jawnym tekstem."""
+    key = link_crypto.key_from_env(link_crypto.ENV_PRESENTATION_LOGIC)
+    return link_crypto.Link(key) if key else None
+
+
+class LogicClient:
+    """Rozmówca warstwy logicznej ZWIĄZANY Z PULĄ KONTA (PRE-29).
+
+    Pulę podaje się przy tworzeniu klienta, a bierze się ją WYŁĄCZNIE z loginu
+    zalogowanej osoby — nigdy z pola formularza. Gdyby przychodziła z żądania,
+    wystarczyłoby podstawić cudzy login, żeby czytać cudze bazy."""
+
+    def __init__(self, tenant: str = "", base_url: str | None = None) -> None:
+        self.base_url = (base_url or settings.logic_url).rstrip("/")
+        self.tenant = tenant or ""
+
+    def report(self, when_utc_iso: str, lat: float, lon: float) -> dict[str, Any]:
+        """Interpretacja urodzeniowa: sygnifikatory z obliczeń szukane w bazach.
+
+        Jedyne pytanie, jakie astrodemo zadaje o treść — bez grupowania,
+        bez grupowania i bez żadnej obróbki treści."""
+        payload = {"when_utc": when_utc_iso, "lat": lat, "lon": lon,
+                   "limit": settings.report_limit, "group": False,
+                   "tenant": self.tenant}
+        with httpx.Client(timeout=settings.http_timeout) as client:
+            return link_crypto.call_json(client, "POST", f"{self.base_url}/chart/report",
+                                         payload=payload, headers=_auth_headers(), link=_link())
+
+    def files_upload(self, filename: str, content_b64: str, by: str = "") -> dict[str, Any]:
+        with httpx.Client(timeout=max(settings.http_timeout, 60.0)) as client:
+            return link_crypto.call_json(
+                client, "POST", f"{self.base_url}/files/upload",
+                payload={"filename": filename, "content_b64": content_b64,
+                         "by": by, "tenant": self.tenant},
+                headers=_auth_headers(), link=_link())
+
+    def files_status(self, path: str, status: str, by: str = "") -> dict[str, Any]:
+        """Włączenie wgranego pliku do użytku. W demo wgranie i włączenie to JEDNA
+        czynność: „dodać do bazy" ma znaczyć, że plik od razu bierze udział
+        w wyszukiwaniu — inaczej demo wyglądałoby na zepsute."""
+        with httpx.Client(timeout=settings.http_timeout) as client:
+            return link_crypto.call_json(
+                client, "POST", f"{self.base_url}/files/status",
+                payload={"path": path, "status": status, "by": by, "tenant": self.tenant},
+                headers=_auth_headers(), link=_link())
+
+    def health(self) -> dict[str, Any]:
+        with httpx.Client(timeout=settings.http_timeout) as client:
+            r = client.get(f"{self.base_url}/health", headers=_auth_headers())
+            r.raise_for_status()
+            return r.json()

services/astrodemo/app/config.py

@@ -0,0 +1,22 @@
+"""Konfiguracja astrodemo — wersji demonstracyjnej (PRE-28).
+
+Zna WYŁĄCZNIE adres warstwy logicznej. Nie wie nic o bazach, Excelu ani SQL-u.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Settings:
+    logic_url: str = field(default_factory=lambda: os.getenv("LOGIC_URL", "http://localhost:8001"))
+    # Szukanie interpretacji potrafi zajrzeć do wszystkich baz naraz, więc limit
+    # czasu jest wyższy niż domyślny dla zwykłego żądania.
+    http_timeout: float = field(default_factory=lambda: float(os.getenv("HTTP_TIMEOUT", "30")))
+    # Górny limit rekordów w jednej odpowiedzi. Nie jest to optymalizacja, tylko
+    # ograniczenie, ile treści baz może wyjść jednym zapytaniem.
+    report_limit: int = field(default_factory=lambda: int(os.getenv("REPORT_LIMIT", "2000")))
+
+
+settings = Settings()

services/astrodemo/app/link_crypto.py

@@ -0,0 +1,525 @@
+"""Szyfrowanie łączy między warstwami (PRE-16 / LOG-33).
+
+Do tej pory warstwy rozmawiały ze sobą zwykłym HTTP-em wewnątrz klastra. Token
+międzywarstwowy (LOG-32) mówił KTO pyta, ale nie ukrywał CZEGO dotyczy odpowiedź
+— a płyną nią surowe wiersze oryginalnych baz interpretacyjnych, czyli rdzeń
+produktu. Kto podsłuchał ruch wewnątrz sieci (drugi pod, port mirror na switchu,
+zrzut z węzła), miał je w całości.
+
+Ten moduł zamyka tę drogę: **AES-256-GCM** na ciele każdego żądania i odpowiedzi.
+GCM daje jednocześnie poufność i uwierzytelnienie — cudzy albo podmieniony bajt
+nie odszyfruje się w ogóle, więc nie ma osobnego problemu „zaszyfrowane, ale
+podatne na modyfikację".
+
+**Dwa niezależne klucze**, po jednym na parę rozmówców:
+  * ``LINK_KEY_PRESENTATION_LOGIC`` — prezentacja ↔ logika,
+  * ``LINK_KEY_LOGIC_DATA``        — logika ↔ dane.
+Dzięki temu przejęcie klucza prezentacji nie daje dostępu do warstwy danych,
+gdzie leżą całe bazy. Logika trzyma oba, bo rozmawia w obie strony.
+
+Z każdego klucza łącza wyprowadzamy **osobne podklucze na kierunek** (HKDF).
+Żądanie i odpowiedź nigdy nie szyfrują się tym samym kluczem, więc powtórzenie
+losowej jednorazówki w jedną stronę nie osłabia drugiej.
+
+Format ramki (bo strumień odpowiedzi może iść kawałkami — patrz okno postępu):
+
+    [4 bajty długości][magia "AL1"][12 bajtów jednorazówki][szyfrogram + znacznik]
+
+Do materiału uwierzytelnianego (AAD) wchodzą kierunek, ścieżka, znacznik czasu
+i numer ramki. Skutek: ramki nie da się przekleić do innego endpointu, odtworzyć
+po czasie (dopuszczalny poślizg ``MAX_SKEW``) ani przestawić w strumieniu.
+
+Bez ustawionego klucza moduł **przepuszcza ruch otwartym tekstem** (dev, zgodność
+wstecz) i krzyczy o tym przy starcie. Gdy klucz JEST ustawiony, warstwa serwerowa
+działa fail-closed: nieszyfrowane żądanie dostaje odmowę, żeby przypadkowa
+regresja po stronie klienta nie oznaczała cichego powrotu do jawnego ruchu.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import logging
+import os
+import struct
+import time
+from typing import Iterable, Iterator
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+log = logging.getLogger("astrololo.link")
+
+MAGIC = b"AL1"
+VERSION = "v1"
+NONCE_BYTES = 12
+KEY_BYTES = 32                      # AES-256
+LENGTH_PREFIX = 4
+MAX_FRAME = 64 * 1024 * 1024        # zapora przed alokacją z podanej długości
+MAX_SKEW_SECONDS = 300.0
+
+HEADER_ENC = "X-Astrololo-Enc"
+HEADER_TS = "X-Astrololo-Enc-Ts"
+CONTENT_TYPE = "application/vnd.astrololo.enc"
+
+ENV_PRESENTATION_LOGIC = "LINK_KEY_PRESENTATION_LOGIC"
+ENV_LOGIC_DATA = "LINK_KEY_LOGIC_DATA"
+# Trzecia para: prezentacja ↔ render (PRE-24). Osobny klucz, jak przy pozostałych —
+# usługa render dostaje CAŁY raport (dane urodzeniowe + opisy z baz), więc przejęcie
+# jej klucza nie może otwierać łącza do logiki ani do danych.
+ENV_PRESENTATION_RENDER = "LINK_KEY_PRESENTATION_RENDER"
+ENV_REQUIRED = "LINK_ENCRYPTION_REQUIRED"
+
+REQUEST, RESPONSE = b"req", b"res"
+
+# Sondy k8s pukają tu bez klucza i tak ma zostać — inaczej pierwsza literówka
+# w sekrecie kładłaby pody zamiast pokazać błąd w aplikacji.
+PUBLIC_PATHS = frozenset({"/health"})
+
+
+class LinkError(Exception):
+    """Cokolwiek poszło nie tak z kopertą — celowo bez szczegółów na zewnątrz."""
+
+
+# --------------------------------------------------------------------- klucze
+
+def parse_key(raw: str) -> bytes:
+    """Klucz z konfiguracji: hex (64 znaki) albo base64. Zawsze 32 bajty."""
+    text = raw.strip()
+    if not text:
+        raise LinkError("pusty klucz łącza")
+    try:
+        key = bytes.fromhex(text)
+    except ValueError:
+        try:
+            key = base64.b64decode(text, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise LinkError("klucz łącza nie jest ani hexem, ani base64") from exc
+    if len(key) != KEY_BYTES:
+        raise LinkError(
+            f"klucz łącza ma {len(key)} B zamiast {KEY_BYTES} — wygeneruj przez "
+            f"`openssl rand -hex 32`"
+        )
+    return key
+
+
+def key_from_env(env_name: str) -> bytes | None:
+    """Klucz albo None. Zły klucz to wyjątek OD RAZU — nie przy pierwszym żądaniu."""
+    raw = os.getenv(env_name, "")
+    return parse_key(raw) if raw.strip() else None
+
+
+def encryption_required() -> bool:
+    """Czy brak klucza ma być błędem, a nie cichym powrotem do jawnego ruchu.
+
+    Serwer sam z siebie broni się fail-closed, ale to za mało: klient BEZ klucza
+    wysyła pytanie otwartym tekstem i dopiero potem dostaje odmowę — czyli treść
+    zapytania zdążyła już przelecieć przez sieć. Ta flaga zatrzymuje go, zanim
+    cokolwiek opuści proces. Ustawiana razem z kluczami we wdrożeniu.
+    """
+    return os.getenv(ENV_REQUIRED, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _subkey(link_key: bytes, direction: bytes) -> bytes:
+    return HKDF(
+        algorithm=hashes.SHA256(), length=KEY_BYTES, salt=None,
+        info=b"astrololo/link/" + direction,
+    ).derive(link_key)
+
+
+class Link:
+    """Jedna para rozmówców: klucz plus wyprowadzone z niego podklucze."""
+
+    def __init__(self, link_key: bytes) -> None:
+        self._by_direction = {
+            REQUEST: AESGCM(_subkey(link_key, REQUEST)),
+            RESPONSE: AESGCM(_subkey(link_key, RESPONSE)),
+        }
+
+    # ---------------------------------------------------------- pojedyncza ramka
+
+    def _aad(self, direction: bytes, path: str, stamp: str, seq: int) -> bytes:
+        return b"|".join([MAGIC, direction, path.encode("utf-8"),
+                          stamp.encode("ascii"), str(seq).encode("ascii")])
+
+    def seal(self, direction: bytes, path: str, stamp: str, seq: int,
+             plaintext: bytes) -> bytes:
+        nonce = os.urandom(NONCE_BYTES)
+        sealed = self._by_direction[direction].encrypt(
+            nonce, plaintext, self._aad(direction, path, stamp, seq))
+        return MAGIC + nonce + sealed
+
+    def open(self, direction: bytes, path: str, stamp: str, seq: int,
+             frame: bytes) -> bytes:
+        if not frame.startswith(MAGIC):
+            raise LinkError("ramka bez znacznika protokołu")
+        body = frame[len(MAGIC):]
+        if len(body) <= NONCE_BYTES:
+            raise LinkError("ramka za krótka")
+        nonce, sealed = body[:NONCE_BYTES], body[NONCE_BYTES:]
+        try:
+            return self._by_direction[direction].decrypt(
+                nonce, sealed, self._aad(direction, path, stamp, seq))
+        except InvalidTag as exc:
+            # Jeden komunikat na wszystkie przypadki: zły klucz, podmieniony bajt,
+            # przeklejenie z innej ścieżki, przestawiona ramka. Rozróżnianie ich
+            # na zewnątrz podpowiadałoby atakującemu, w co trafił.
+            raise LinkError("nie udało się odszyfrować — zły klucz albo naruszone dane") from exc
+
+    # ------------------------------------------------------------ strumień ramek
+
+    def seal_stream(self, direction: bytes, path: str, stamp: str,
+                    chunks: Iterable[bytes]) -> Iterator[bytes]:
+        for seq, chunk in enumerate(chunks):
+            yield frame_out(self.seal(direction, path, stamp, seq, chunk))
+
+    def open_stream(self, direction: bytes, path: str, stamp: str,
+                    raw: bytes) -> Iterator[bytes]:
+        for seq, frame in enumerate(frames_in(raw)):
+            yield self.open(direction, path, stamp, seq, frame)
+
+    def open_all(self, direction: bytes, path: str, stamp: str, raw: bytes) -> bytes:
+        return b"".join(self.open_stream(direction, path, stamp, raw))
+
+
+# ---------------------------------------------------------------- ramkowanie
+
+def frame_out(payload: bytes) -> bytes:
+    return struct.pack(">I", len(payload)) + payload
+
+
+def frames_in(raw: bytes) -> Iterator[bytes]:
+    """Rozbiera bufor na ramki. Ucięty strumień to błąd, nie cicha strata danych."""
+    offset = 0
+    while offset < len(raw):
+        if offset + LENGTH_PREFIX > len(raw):
+            raise LinkError("urwana ramka (brak nagłówka długości)")
+        (size,) = struct.unpack(">I", raw[offset:offset + LENGTH_PREFIX])
+        if size > MAX_FRAME:
+            raise LinkError("ramka ponad dopuszczalny rozmiar")
+        offset += LENGTH_PREFIX
+        if offset + size > len(raw):
+            raise LinkError("urwana ramka (za mało danych)")
+        yield raw[offset:offset + size]
+        offset += size
+
+
+def unframe_incremental(buffer: bytearray) -> Iterator[bytes]:
+    """Wyjmuje z bufora KOMPLETNE ramki i zjada je; resztę zostawia na później.
+
+    Dla odbioru na żywo: kawałki przychodzą podzielone dowolnie i ramka potrafi
+    rozjechać się między dwa odczyty.
+    """
+    while True:
+        if len(buffer) < LENGTH_PREFIX:
+            return
+        (size,) = struct.unpack(">I", buffer[:LENGTH_PREFIX])
+        if size > MAX_FRAME:
+            raise LinkError("ramka ponad dopuszczalny rozmiar")
+        if len(buffer) < LENGTH_PREFIX + size:
+            return
+        frame = bytes(buffer[LENGTH_PREFIX:LENGTH_PREFIX + size])
+        del buffer[:LENGTH_PREFIX + size]
+        yield frame
+
+
+# ------------------------------------------------------------- świeżość ruchu
+
+def stamp_now() -> str:
+    return f"{time.time():.3f}"
+
+
+def check_stamp(stamp: str) -> None:
+    """Odrzuca ramki spoza okna czasowego — inaczej podsłuchane żądanie dałoby się
+    odtworzyć w dowolnym momencie w przyszłości."""
+    try:
+        sent = float(stamp)
+    except (TypeError, ValueError) as exc:
+        raise LinkError("brak albo błędny znacznik czasu") from exc
+    if abs(time.time() - sent) > MAX_SKEW_SECONDS:
+        raise LinkError("znacznik czasu poza dopuszczalnym oknem")
+
+
+# =========================================================== strona serwerowa
+
+class LinkCryptoMiddleware:
+    """Rozszyfrowuje wchodzące żądania i zaszyfrowuje wychodzące odpowiedzi.
+
+    Napisane jako czyste ASGI, nie ``@app.middleware("http")``, bo trzeba
+    podmienić CIAŁO żądania jeszcze zanim zobaczy je FastAPI, oraz przepuścić
+    odpowiedź strumieniową kawałek po kawałku, bez zbierania jej w pamięci.
+    """
+
+    def __init__(self, app, link: Link | None, layer: str) -> None:
+        self.app = app
+        self.link = link
+        self.layer = layer
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http" or self.link is None or scope["path"] in PUBLIC_PATHS:
+            return await self.app(scope, receive, send)
+
+        path = scope["path"]
+        headers = {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope["headers"]}
+
+        if headers.get(HEADER_ENC.lower()) != VERSION:
+            # Fail-closed. Klucz jest ustawiony, więc jawne żądanie oznacza albo
+            # pomyłkę w konfiguracji, albo kogoś obcego — w obu wypadkach nie
+            # chcemy po cichu wrócić do jawnego ruchu.
+            log.warning("warstwa %s: odrzucone żądanie bez szyfrowania łącza (%s)",
+                        self.layer, path)
+            return await _refuse(send, "Łącze międzywarstwowe wymaga szyfrowania.")
+
+        stamp = headers.get(HEADER_TS.lower(), "")
+        try:
+            check_stamp(stamp)
+            plaintext = self.link.open_all(REQUEST, path, stamp, await _read_body(receive))
+        except LinkError as exc:
+            log.warning("warstwa %s: %s (%s)", self.layer, exc, path)
+            return await _refuse(send, "Nie udało się odczytać zaszyfrowanego żądania.")
+
+        scope = dict(scope)
+        scope["headers"] = _rewritten_headers(scope["headers"], len(plaintext))
+        await self.app(scope, _replay(plaintext, receive), self._sealing_send(send, path))
+
+    def _sealing_send(self, send, path: str):
+        state: dict = {"stamp": "", "seq": 0}
+
+        async def sealing(message):
+            if message["type"] == "http.response.start":
+                state["stamp"] = stamp_now()
+                keep = [(k, v) for k, v in message.get("headers", [])
+                        if k.lower() not in (b"content-length", b"content-type")]
+                message = dict(message)
+                message["headers"] = keep + [
+                    (b"content-type", CONTENT_TYPE.encode()),
+                    (HEADER_ENC.lower().encode(), VERSION.encode()),
+                    (HEADER_TS.lower().encode(), state["stamp"].encode()),
+                ]
+                return await send(message)
+
+            if message["type"] == "http.response.body":
+                chunk = message.get("body", b"")
+                sealed = b""
+                if chunk:
+                    sealed = frame_out(self.link.seal(
+                        RESPONSE, path, state["stamp"], state["seq"], chunk))
+                    state["seq"] += 1
+                return await send({"type": "http.response.body", "body": sealed,
+                                   "more_body": message.get("more_body", False)})
+
+            return await send(message)
+
+        return sealing
+
+
+def _rewritten_headers(raw: Iterable[tuple[bytes, bytes]], length: int):
+    """Po odszyfrowaniu ciało ma inną długość i zwykły typ — inaczej FastAPI
+    próbowałby sparsować JSON o cudzej deklarowanej wielkości."""
+    kept = [(k, v) for k, v in raw if k.lower() not in (b"content-length", b"content-type")]
+    kept.append((b"content-length", str(length).encode()))
+    if length:
+        kept.append((b"content-type", b"application/json"))
+    return kept
+
+
+async def _read_body(receive) -> bytes:
+    body = bytearray()
+    while True:
+        message = await receive()
+        if message["type"] == "http.disconnect":
+            raise LinkError("rozłączenie w trakcie odbioru żądania")
+        body += message.get("body", b"")
+        if not message.get("more_body", False):
+            return bytes(body)
+
+
+def _replay(body: bytes, original):
+    """Podstawia odszyfrowane ciało jako jedyną porcję wejścia dla aplikacji.
+
+    Po oddaniu ciała oddajemy głos ORYGINALNEMU `receive`, zamiast od razu
+    zgłaszać rozłączenie. Odpowiedź strumieniowa nasłuchuje bowiem rozłączenia
+    równolegle do wysyłania i przerywa się, gdy je zobaczy — na skróconej wersji
+    okno postępu dostawało pustą odpowiedź, choć zwykłe żądania działały.
+    """
+    delivered = False
+
+    async def receive():
+        nonlocal delivered
+        if delivered:
+            return await original()
+        delivered = True
+        return {"type": "http.request", "body": body, "more_body": False}
+
+    return receive
+
+
+async def _refuse(send, detail: str) -> None:
+    """Odmowa leci JAWNIE — rozmówca właśnie pokazał, że nie umie odszyfrować,
+    więc zaszyfrowany komunikat o błędzie byłby dla niego nieczytelny."""
+    payload = f'{{"detail":"{detail}"}}'.encode("utf-8")
+    await send({"type": "http.response.start", "status": 400, "headers": [
+        (b"content-type", b"application/json"),
+        (b"content-length", str(len(payload)).encode()),
+    ]})
+    await send({"type": "http.response.body", "body": payload})
+
+
+def install(app, env_name: str, layer: str):
+    """Podpina szyfrowanie łącza. Wołać PO `security.install`, żeby także odmowa
+    tokenowa (401) wracała zaszyfrowana — inaczej klient by jej nie odczytał."""
+    link_key = key_from_env(env_name)
+    if link_key is None and encryption_required():
+        # Celowo wywracamy start. Ta sama zasada co przy sekrecie logowania:
+        # wolimy widoczną awarię niż usługę, która wstała i po cichu nie chroni
+        # niczego. Pod w CrashLoop widać od razu, jawny ruch — nie.
+        raise LinkError(
+            f"{ENV_REQUIRED} jest włączone, ale {env_name} nie ustawiony — "
+            f"warstwa {layer} nie wystartuje bez klucza łącza"
+        )
+    if link_key is None:
+        log.warning(
+            "UWAGA: %s nie ustawiony — warstwa %s rozmawia z sąsiadem JAWNYM tekstem, "
+            "więc treść baz interpretacyjnych jest widoczna dla każdego, kto podsłucha "
+            "ruch wewnątrz sieci.", env_name, layer,
+        )
+        return None
+    link = Link(link_key)
+    app.add_middleware(LinkCryptoMiddleware, link=link, layer=layer)
+    log.info("warstwa %s: łącze szyfrowane (AES-256-GCM, klucz z %s)", layer, env_name)
+    return link
+
+
+# ============================================================ strona kliencka
+
+def call(client, method: str, url: str, *, payload=None,
+         headers: dict[str, str] | None = None, link: Link | None) -> bytes:
+    """Żądanie do sąsiedniej warstwy; zwraca odszyfrowane ciało odpowiedzi.
+
+    Ścieżkę do materiału uwierzytelnianego bierzemy Z URL-a, a nie z osobnego
+    argumentu — gdyby klient i serwer liczyły ją inaczej, każde żądanie kończyłoby
+    się niejasnym błędem odszyfrowania.
+    """
+    import json as _json
+
+    import httpx
+
+    request_headers = dict(headers or {})
+    if link is None:
+        if encryption_required():
+            # Zatrzymujemy się PRZED wysłaniem. Gdyby polecieć jawnie i dopiero
+            # zebrać odmowę, pytanie byłoby już na kablu — a to właśnie ono niesie
+            # sygnifikatory, o które pytamy bazę.
+            raise LinkError(
+                f"{ENV_REQUIRED} jest włączone, ale brak klucza łącza — żądanie "
+                f"NIE zostało wysłane, żeby jego treść nie poszła jawnym tekstem"
+            )
+        response = client.request(method, url, json=payload, headers=request_headers)
+        response.raise_for_status()
+        return response.content
+
+    path = httpx.URL(url).path
+    stamp = stamp_now()
+    plaintext = b"" if payload is None else _json.dumps(payload).encode("utf-8")
+    body = frame_out(link.seal(REQUEST, path, stamp, 0, plaintext))
+    request_headers.update({HEADER_ENC: VERSION, HEADER_TS: stamp,
+                            "Content-Type": CONTENT_TYPE})
+
+    response = client.request(method, url, content=body, headers=request_headers)
+    if response.status_code >= 400 and response.headers.get(HEADER_ENC) != VERSION:
+        log.error("łącze %s odmówiło: %s", path, response.text[:200])
+    response.raise_for_status()
+    if response.headers.get(HEADER_ENC) != VERSION:
+        raise LinkError("odpowiedź przyszła nieszyfrowana, choć klucz łącza jest ustawiony")
+    reply_stamp = response.headers.get(HEADER_TS, "")
+    check_stamp(reply_stamp)
+    return link.open_all(RESPONSE, path, reply_stamp, response.content)
+
+
+def call_json(client, method: str, url: str, *, payload=None,
+              headers: dict[str, str] | None = None, link: Link | None):
+    import json as _json
+
+    return _json.loads(call(client, method, url, payload=payload,
+                            headers=headers, link=link))
+
+
+def open_response_stream(response, link: Link | None) -> Iterator[bytes]:
+    """Odbiór odpowiedzi płynącej kawałkami (okno postępu).
+
+    Ramka potrafi rozjechać się między dwa odczyty z gniazda, więc składamy ją
+    w buforze zamiast zakładać, że każdy kawałek to komplet.
+    """
+    if link is None:
+        yield from response.iter_bytes()
+        return
+    if response.headers.get(HEADER_ENC) != VERSION:
+        raise LinkError("strumień przyszedł nieszyfrowany, choć klucz łącza jest ustawiony")
+    stamp = response.headers.get(HEADER_TS, "")
+    check_stamp(stamp)
+    path = response.request.url.path
+    buffer = bytearray()
+    seq = 0
+    for chunk in response.iter_bytes():
+        buffer += chunk
+        for frame in unframe_incremental(buffer):
+            yield link.open(RESPONSE, path, stamp, seq, frame)
+            seq += 1
+    if buffer:
+        raise LinkError("strumień urwał się w połowie ramki")
+
+
+def stream_lines(client, url: str, *, payload, headers: dict[str, str] | None = None,
+                 link: Link | None) -> Iterator[str]:
+    """Strumieniowe POST zwracające kolejne NIEPUSTE linie NDJSON — na żywo.
+
+    Dla okna postępu: linie muszą docierać w trakcie pracy, nie na końcu, więc
+    czytamy strumień, a nie całe ciało. Gdy łącze ma klucz, żądanie jest
+    pieczętowane, a odpowiedź odszyfrowywana ramka po ramce; granice ramek NIE
+    pokrywają się z granicami linii, więc sklejamy bajty w buforze i tniemy je
+    dopiero na znakach nowej linii.
+
+    Bez klucza zachowuje się jak dotąd (surowy strumień), żeby dev bez sekretów
+    działał bez zmian.
+    """
+    import json as _json
+
+    import httpx as _httpx
+
+    request_headers = dict(headers or {})
+    if link is None:
+        if encryption_required():
+            # Ten sam kontrakt co w `call`: nie wypuszczamy jawnego żądania, gdy
+            # szyfrowanie jest wymagane. Bez tego serwer owszem odrzuca (400), ale
+            # ciało żądania — tu dane urodzenia — zdążyłoby już pójść w eter.
+            raise LinkError(
+                f"{ENV_REQUIRED} jest włączone, ale brak klucza łącza — strumień "
+                f"NIE został wysłany, żeby jego treść nie poszła jawnym tekstem"
+            )
+        with client.stream("POST", url, json=payload, headers=request_headers) as response:
+            response.raise_for_status()
+            for text_line in response.iter_lines():
+                if text_line:
+                    yield text_line
+        return
+
+    path = _httpx.URL(url).path
+    stamp = stamp_now()
+    body = frame_out(link.seal(REQUEST, path, stamp, 0, _json.dumps(payload).encode("utf-8")))
+    request_headers.update({HEADER_ENC: VERSION, HEADER_TS: stamp, "Content-Type": CONTENT_TYPE})
+    with client.stream("POST", url, content=body, headers=request_headers) as response:
+        response.raise_for_status()
+        buffer = bytearray()
+        for plain in open_response_stream(response, link):
+            buffer += plain
+            while True:
+                nl = buffer.find(b"\n")
+                if nl < 0:
+                    break
+                text_line = bytes(buffer[:nl])
+                del buffer[:nl + 1]
+                if text_line:
+                    yield text_line.decode("utf-8")
+        if buffer:
+            yield bytes(buffer).decode("utf-8")

services/astrodemo/app/main.py

@@ -0,0 +1,255 @@
+"""astrodemo — wersja DEMONSTRACYJNA (PRE-28).
+
+DWIE FUNKCJE I ANI JEDNEJ WIĘCEJ:
+  1. dodanie pliku bazy (wgranie + włączenie do użytku),
+  2. zapytanie o interpretację urodzeniową dla podanych danych wejściowych.
+
+DLACZEGO OSOBNA USŁUGA, A NIE KONTO Z OGRANICZENIAMI. Ukrycie a nieobecność to
+dwie różne rzeczy. Tutaj niczego poza tymi dwiema funkcjami NIE MA W OBRAZIE: nie
+ma tras, nie ma szablonów, nie ma nawet metod w kliencie warstwy logicznej. Obraz
+tej usługi można komuś oddać i nie oddaje się przy tym niczego ponad to, co widać
+na ekranie — łącznie z komentarzami w tym pliku, bo one też jadą razem z obrazem.
+
+PULE SĄ ROZDZIELONE (PRE-29). Każde konto ma własny, izolowany zbiór plików,
+niewidoczny dla pozostałych kont; pula bierze się WYŁĄCZNIE z loginu zalogowanej
+osoby, nigdy z pola formularza. Konta są osobne (ASTRODEMO_USERS) — żeby dało się
+odciąć tę usługę jedną zmienną, bez
+ruszania kont głównej aplikacji.
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import re
+from functools import lru_cache
+from pathlib import Path
+from datetime import datetime, timedelta, timezone
+
+import httpx
+from fastapi import FastAPI, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import HTMLResponse, RedirectResponse, Response
+from fastapi.templating import Jinja2Templates
+
+from app import link_crypto, security, session
+from app.clients.logic_client import LogicClient
+
+# Automatyczna dokumentacja WYŁĄCZONA. /docs wypisałoby komplet tras, a ta usługa
+# ma nie zdradzać nawet własnej powierzchni.
+app = FastAPI(title="astrodemo", docs_url=None, redoc_url=None, openapi_url=None)
+security.install(app)
+
+# ── zasoby (PRE-27) ────────────────────────────────────────────────────────
+# Katalog NIE jest montowany. Montowanie serwuje wszystko, co w nim leży, każdemu
+# i bez śladu w dzienniku — a komentarz w arkuszu stylów mówił wprost, że istnieje
+# więcej, niż widać na ekranie. Tu jest jawna lista: arkusz logowania jest
+# publiczny, bo
+# potrzebuje go strona logowania, a cokolwiek innego jest nieznane i nie istnieje.
+ZASOBY_PUBLICZNE = frozenset({"styles.css"})
+_KATALOG_ZASOBOW = Path("app/static")
+
+
+def _bez_komentarzy(tresc: str) -> str:
+    """Komentarz w pliku statycznym jedzie do przeglądarki bajt w bajt.
+    W repozytorium zostaje — do odpowiedzi nie ma po co trafiać."""
+    tresc = re.sub(r"/\*.*?\*/", "", tresc, flags=re.S)
+    return re.sub(r"\n{3,}", "\n\n", tresc).strip() + "\n"
+
+
+@lru_cache(maxsize=None)
+def _zasob(nazwa: str) -> bytes | None:
+    """Treść zasobu tak, jak pójdzie na drut — albo None, gdy go nie ma."""
+    if nazwa not in ZASOBY_PUBLICZNE:
+        return None
+    sciezka = (_KATALOG_ZASOBOW / nazwa).resolve()
+    # Wyjście poza katalog: `..` w ścieżce albo dowiązanie na zewnątrz.
+    if _KATALOG_ZASOBOW.resolve() not in sciezka.parents or not sciezka.is_file():
+        return None
+    if sciezka.suffix in (".css", ".js"):
+        return _bez_komentarzy(sciezka.read_text(encoding="utf-8")).encode("utf-8")
+    return sciezka.read_bytes()
+
+
+@app.get("/static/{nazwa:path}")
+def zasob(nazwa: str):
+    tresc = _zasob(nazwa)
+    if tresc is None:
+        raise HTTPException(status_code=404)
+    typ = "text/css; charset=utf-8" if nazwa.endswith(".css") else "application/octet-stream"
+    return Response(tresc, media_type=typ,
+                    headers={"Cache-Control": "public, max-age=3600"})
+
+templates = Jinja2Templates(directory="app/templates")
+# Szczegóły awarii idą TUTAJ, nie na ekran (patrz _blad).
+log = logging.getLogger("astrodemo")
+templates.env.globals["current_user"] = lambda request: getattr(request.state, "user", "") or ""
+templates.env.globals["auth_on"] = security.auth_enabled
+
+def _logic(request: Request) -> LogicClient:
+    """Klient związany z pulą ZALOGOWANEGO konta.
+
+    Budowany PER ŻĄDANIE, nie raz na moduł: pula musi wynikać z tego, kto się
+    zalogował, a nie z globalnego stanu procesu. Login bierzemy z request.state,
+    które ustawia warstwa logowania — nigdy z pola formularza, bo wtedy
+    wystarczyłoby podstawić cudzy login, żeby czytać cudze bazy."""
+    return LogicClient(tenant=getattr(request.state, "user", "") or "")
+
+# Stan pliku „w użyciu" — ta sama nazwa, co w warstwie danych (DAN-27). Wpisana
+# tutaj wprost, bo astrodemo nie importuje tamtej warstwy; literówka objawiłaby
+# się dopiero na żywo, więc pilnuje jej test.
+ACTIVE = "active"
+
+
+def _build_utc(date: str, time: str, tz_offset: float) -> tuple[str, str]:
+    """Data + godzina lokalna + offset → chwila w UTC.
+
+    Offset podaje się wprost, bez wyszukiwania strefy z współrzędnych — demo ma
+    dwie funkcje, a strefy to trzecia."""
+    try:
+        local = datetime.strptime(f"{date} {time}", "%Y-%m-%d %H:%M")
+    except ValueError as e:
+        raise ValueError("Podaj datę jako RRRR-MM-DD i godzinę jako GG:MM.") from e
+    moment = local.replace(tzinfo=timezone(timedelta(hours=tz_offset)))
+    return moment.astimezone(timezone.utc).isoformat(), local.strftime("%Y-%m-%d %H:%M")
+
+
+# Jedno zdanie dla wszystkich awarii i CELOWO żadnego szczegółu. Treść wyjątku
+# niosła nazwę usługi, jej port i nazwy jej tras — czyli mapę tego, co stoi za tym
+# ekranem, podaną komuś, kto ma widzieć wyłącznie dwa formularze.
+_AWARIA = "Nie udało się teraz wykonać tej operacji. Spróbuj ponownie za chwilę."
+
+
+def _blad(e: Exception) -> str:
+    """Komunikat dla użytkownika. Diagnostyka idzie do dziennika, nie na ekran."""
+    log.warning("operacja nieudana: %s: %s", type(e).__name__, e)
+    return _AWARIA
+
+
+def _ile_rekordow(report: dict) -> int:
+    return sum(len(s.get("samples") or []) for p in (report.get("positions") or [])
+               for s in (p.get("significators") or []))
+
+
+@app.get("/", response_class=HTMLResponse)
+def formularz(request: Request, error: str = "", done: str = ""):
+    return templates.TemplateResponse(request, "index.html",
+                                      {"result": None, "form": {}, "error": error, "done": done})
+
+
+@app.post("/", response_class=HTMLResponse)
+def interpretacja(request: Request, date: str = Form(...), time: str = Form(...),
+                  tz_offset: float = Form(0.0), lat: float = Form(0.0), lon: float = Form(0.0)):
+    """Interpretacja urodzeniowa dla podanych danych. Jedyne pytanie o treść."""
+    form = {"date": date, "time": time, "tz_offset": tz_offset, "lat": lat, "lon": lon}
+    ctx: dict = {"form": form, "result": None, "error": None, "done": "", "moment": None}
+    try:
+        iso_utc, label = _build_utc(date, time, tz_offset)
+        ctx["moment"] = label
+        ctx["result"] = _logic(request).report(when_utc_iso=iso_utc, lat=lat, lon=lon)
+        # Ile treści baz wyszło jednym zapytaniem — sama liczba, nigdy treść (PRE-17).
+        security.audit_records(request, _ile_rekordow(ctx["result"]))
+    except ValueError as e:
+        ctx["error"] = str(e)
+    except (httpx.HTTPError, link_crypto.LinkError) as e:
+        ctx["error"] = _blad(e)
+    return templates.TemplateResponse(request, "index.html", ctx)
+
+
+@app.post("/plik")
+async def dodaj_plik(request: Request, upload: UploadFile = File(...)):
+    """Dodanie pliku bazy: wgranie ORAZ włączenie do użytku.
+
+    Jedna czynność, nie dwie: „dodać plik" ma tu znaczyć, że od razu bierze udział
+    w wyszukiwaniu — inaczej po wgraniu nic by się nie zmieniło i wyglądałoby to
+    na zepsute.
+
+    Plik o złym układzie nie wchodzi do użytku, ale NIE JEST tracony — zostaje
+    zapisany i czeka."""
+    raw = await upload.read()
+    if not raw:
+        return RedirectResponse("/?error=Pusty+plik.", status_code=303)
+
+    who = getattr(request.state, "user", "") or "demo"
+    try:
+        out = _logic(request).files_upload(upload.filename or "baza.xlsx",
+                                 base64.b64encode(raw).decode("ascii"), by=who)
+    except (httpx.HTTPError, link_crypto.LinkError) as e:
+        return _wroc(error=_blad(e))
+
+    nazwa = out.get("name") or "plik"
+    if not out.get("accepted"):
+        # Bez słowa o regułach — te zna wyłącznie administrator (DAN-27).
+        return _wroc(done=f"Plik „{nazwa}” został przyjęty, ale nie nadaje się "
+                          f"do użycia w tej postaci.")
+    try:
+        _logic(request).files_status(out["path"], ACTIVE, by=who)
+    except (httpx.HTTPError, link_crypto.LinkError) as e:
+        return _wroc(error=f"Plik „{nazwa}” wgrany, ale nie udało się go włączyć: {_blad(e)}")
+    return _wroc(done=f"Dodano „{nazwa}”. Baza jest już używana przy wyszukiwaniu.")
+
+
+def _wroc(error: str = "", done: str = "") -> RedirectResponse:
+    """Po zapisie PRZEKIEROWANIE, nie render — odświeżenie strony nie może
+    wgrać pliku drugi raz."""
+    from urllib.parse import urlencode
+
+    q = urlencode({k: v for k, v in (("error", error), ("done", done)) if v})
+    return RedirectResponse(f"/{'?' + q if q else ''}", status_code=303)
+
+
+# ---------------- Logowanie i wylogowanie (LOG-34) ----------------
+# Bez własnego wolumenu nie ma gdzie trzymać licznika pokolenia sesji, więc
+# „wyrzuć ze wszystkich urządzeń" robi się zmianą hasła w ASTRODEMO_USERS.
+# Wylogowanie działa natychmiast, bo polega na skasowaniu ciasteczka.
+
+def _bezpieczne_dokad(dokad: str) -> str:
+    """Adres powrotu przepuszczony przez sito — bez tego `?dokad=https://obcy.pl`
+    zamieniłby ekran logowania w narzędzie do wyłudzania haseł."""
+    dokad = (dokad or "").strip()
+    if not dokad.startswith("/") or dokad.startswith("//") or "\\" in dokad:
+        return "/"
+    return dokad.split("?", 1)[0].split("#", 1)[0] or "/"
+
+
+@app.get("/logowanie", response_class=HTMLResponse)
+def logowanie_form(request: Request, dokad: str = "/", blad: str = ""):
+    if security.auth_enabled() and security.principal(request):
+        return RedirectResponse(_bezpieczne_dokad(dokad), status_code=303)
+    return templates.TemplateResponse(request, "logowanie.html",
+                                      {"dokad": _bezpieczne_dokad(dokad), "blad": blad})
+
+
+@app.post("/logowanie")
+def logowanie(request: Request, login: str = Form(""), haslo: str = Form(""),
+              dokad: str = Form("/")):
+    cel = _bezpieczne_dokad(dokad)
+    kto = security.verify(login.strip(), haslo)
+    if kto is None:
+        security.audit_login(request, login.strip(), udane=False)
+        return templates.TemplateResponse(
+            request, "logowanie.html",
+            {"dokad": cel, "blad": "Nieprawidłowy login lub hasło.", "login": login},
+            status_code=401)
+    security.audit_login(request, kto, udane=True)
+    odpowiedz = RedirectResponse(cel, status_code=303)
+    odpowiedz.set_cookie(session.COOKIE, security.issue_session(kto),
+                         max_age=session.max_age(),
+                         **session.cookie_params(secure=security.cookies_secure()))
+    return odpowiedz
+
+
+@app.post("/wyloguj")
+def wyloguj(request: Request):
+    """POST, nie odsyłacz: pod adresem GET wystarczyłby obrazek na obcej stronie,
+    żeby wylogować kogoś bez jego wiedzy."""
+    security.audit_logout(request)
+    odpowiedz = RedirectResponse("/logowanie?wylogowano=1", status_code=303)
+    odpowiedz.delete_cookie(session.COOKIE,
+                            **session.cookie_params(secure=security.cookies_secure()))
+    return odpowiedz
+
+
+@app.get("/health")
+def health() -> dict:
+    # Sama „ok". Nazwa warstwy mówiła, że warstw jest więcej i jak się nazywa;
+    # kubernetes i compose czytają wyłącznie kod odpowiedzi.
+    return {"status": "ok"}

services/astrodemo/app/security.py

@@ -0,0 +1,266 @@
+"""Logowanie do astrodemo (PRE-28).
+
+OSOBNE KONTO, NIE WSPÓŁDZIELONE Z GŁÓWNĄ APLIKACJĄ. Demo pracuje na tej samej
+warstwie danych co produkcja, więc kto ma do niego dostęp, czyta oryginalne bazy
+interpretacyjne. Własny login i hasło pozwalają odciąć demo jedną zmienną
+środowiskową, bez ruszania kont głównej aplikacji i bez zmiany hasła komukolwiek.
+
+Mechanizm jest CELOWO prosty: jedno konto z konfiguracji, bez ekranu kont
+i bez uprawnień. Ta usługa ma dwie funkcje i obie są dla tego samego człowieka —
+model uprawnień z PRE-27 nie miałby tu czego dzielić.
+
+Hasło może być jawne albo jako hash scrypt (`scrypt$sól$hash`), tym samym formatem
+co APP_USERS w głównej aplikacji — dzięki temu skrypt make_user.py działa na oba.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import logging
+import os
+import time
+from collections import deque
+
+from fastapi import Request
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse
+
+log = logging.getLogger("astrodemo.security")
+audit_log = logging.getLogger("astrodemo.audit")
+
+_SCRYPT_N, _SCRYPT_R, _SCRYPT_P, _SCRYPT_LEN = 2**14, 8, 1, 32
+_HASH_PREFIX = "scrypt$"
+
+# /logowanie i /wyloguj poza bramką: inaczej żeby się zalogować, trzeba by być
+# zalogowanym, a wyjście nie działałoby po wygaśnięciu sesji.
+PUBLIC_PATHS = frozenset({"/health", "/logowanie", "/wyloguj", "/static/styles.css"})
+# Pusto CELOWO. Prefiks "/static/" przepuszczał CAŁY katalog obok bramki: każdy
+# plik pobierał ktokolwiek, także niezalogowany, i nie zostawiało to śladu ani
+# w dzienniku, ani w limicie żądań. Publiczny jest jeden arkusz, wymieniony
+# z nazwy, bo potrzebuje go ekran logowania.
+PUBLIC_PREFIXES: tuple[str, ...] = ()
+
+_hits: dict[str, deque[float]] = {}
+MAX_TRACKED_CLIENTS = 4096
+
+
+def accounts() -> dict[str, str]:
+    """Konta demo: `login:sekret`, po przecinku, ze zmiennej ASTRODEMO_USERS.
+
+    WIELE KONT, bo każde ma WŁASNĄ, niewidoczną dla pozostałych pulę baz (PRE-29).
+    Wspólne konto oznaczałoby wspólną pulę, czyli klientów oglądających nawzajem
+    swoje wgrania.
+
+    Sekret najlepiej jako hash scrypt (`scrypt$sól$hash`) — ten sam format i ten
+    sam skrypt make_user.py, co w głównej aplikacji.
+
+    Zgodność wstecz: pojedyncze ASTRODEMO_USER/ASTRODEMO_PASSWORD działa, gdy ASTRODEMO_USERS
+    jest puste."""
+    out: dict[str, str] = {}
+    for entry in os.getenv("ASTRODEMO_USERS", "").split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        user, sep, secret = entry.partition(":")
+        if sep and user.strip() and secret.strip():
+            out[user.strip()] = secret.strip()
+    if out:
+        return out
+    single = os.getenv("ASTRODEMO_PASSWORD", "")
+    return {os.getenv("ASTRODEMO_USER", "demo"): single} if single else {}
+
+
+def rate_limit_per_min() -> int:
+    return int(os.getenv("RATE_LIMIT_PER_MIN", "60"))
+
+
+def trust_proxy() -> bool:
+    return os.getenv("TRUST_PROXY", "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def auth_enabled() -> bool:
+    return bool(accounts())
+
+
+def _secret_matches(spec: str, password: str) -> bool:
+    if spec.startswith(_HASH_PREFIX):
+        try:
+            _, salt_hex, hash_hex = spec.split("$", 2)
+            salt, expected = bytes.fromhex(salt_hex), bytes.fromhex(hash_hex)
+        except ValueError:
+            return False
+        actual = hashlib.scrypt(password.encode("utf-8"), salt=salt,
+                                n=_SCRYPT_N, r=_SCRYPT_R, p=_SCRYPT_P, dklen=_SCRYPT_LEN)
+        return hmac.compare_digest(actual, expected)
+    # BAJTY, nie tekst: compare_digest na stringach rzuca TypeError przy znakach
+    # spoza ASCII, więc hasło z polskimi literami dawałoby 500 zamiast odmowy.
+    return hmac.compare_digest(spec.encode("utf-8"), password.encode("utf-8"))
+
+
+def verify(login: str, password: str) -> str | None:
+    """Sprawdza login i hasło; zwraca login albo None.
+
+    Nieznany login i złe hasło traktujemy tak samo — odmowa nie mówi, które
+    konto istnieje, a przy demo rozdawanym szeroko to realna informacja."""
+    spec = accounts().get(login)
+    if spec is None:
+        return None
+    return login if _secret_matches(spec, password) else None
+
+
+def issue_session(login: str) -> str:
+    """Zawartość ciasteczka dla właśnie zalogowanego konta.
+
+    W ciasteczku ląduje ODCISK poświadczenia, więc zmiana hasła albo usunięcie
+    konta z ASTRODEMO_USERS unieważnia jego sesje samo z siebie. To jest tu jedyny
+    sposób zdalnego unieważnienia: demo nie ma gdzie trwale zapisywać stanu,
+    bo nie ma własnego wolumenu — a stan sesji na udziale z bazami klientów
+    byłby pomieszaniem dwóch zupełnie różnych rzeczy."""
+    from app import session
+
+    return session.issue(login, session.fingerprint(accounts().get(login) or ""), 0)
+
+
+def principal(request: Request) -> str | None:
+    """Ciasteczko → login zalogowanej osoby albo None."""
+    from app import session
+
+    dane = session.read(request.cookies.get(session.COOKIE))
+    if dane is None:
+        return None
+    spec = accounts().get(dane["login"])
+    if spec is None or session.fingerprint(spec) != dane["odcisk"]:
+        return None
+    return dane["login"]
+
+
+def client_ip(request: Request) -> str:
+    """Adres do rozliczania limitu. Nagłówkom wierzymy WYŁĄCZNIE za proxy —
+    inaczej wystarczyłoby podstawić własny X-Forwarded-For, żeby ominąć limit."""
+    peer = request.client.host if request.client else "?"
+    if not trust_proxy():
+        return peer
+    forwarded = request.headers.get("x-forwarded-for", "")
+    if forwarded:
+        last = forwarded.rsplit(",", 1)[-1].strip()
+        if last:
+            return last
+    return request.headers.get("x-real-ip", "").strip() or peer
+
+
+def _rate_limited(client: str) -> bool:
+    cap = rate_limit_per_min()
+    if cap <= 0:
+        return False
+    now = time.monotonic()
+    window = _hits.get(client)
+    if window is None:
+        if len(_hits) >= MAX_TRACKED_CLIENTS:
+            _hits.clear()
+        window = _hits[client] = deque()
+    while window and now - window[0] > 60.0:
+        window.popleft()
+    if len(window) >= cap:
+        return True
+    window.append(now)
+    return False
+
+
+def _setup_audit_logging() -> None:
+    """Własny handler na stdout. Domyślna konfiguracja uvicorna nie obsługuje
+    naszych loggerów, więc wpisy INFO ginęły — dziennik istniał w kodzie, ale był
+    pusty. Niewidoczny dziennik jest gorszy niż jego brak (błąd zastany w PRE-17)."""
+    audit_log.setLevel(os.getenv("AUDIT_LEVEL", "INFO").upper())
+    if not audit_log.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+        audit_log.addHandler(handler)
+    audit_log.propagate = False
+
+
+def audit_records(request: Request, count: int) -> None:
+    try:
+        request.state.audit_records = int(count)
+    except (TypeError, ValueError):
+        pass
+
+
+def cookies_secure() -> bool:
+    """Ciasteczko tylko dla https. Wyłączane wyłącznie w pracy lokalnej po http —
+    inaczej przeglądarka po prostu go nie zapamięta i logowanie „nie działa"
+    bez żadnego komunikatu."""
+    return os.getenv("COOKIES_INSECURE", "").strip().lower() not in {"1", "true", "yes", "on"}
+
+
+def audit_login(request: Request, login: str, udane: bool) -> None:
+    """Zdarzenie logowania. Nieudane próby są ważniejsze od udanych: pojedyncza
+    nic nie znaczy, seria pod jednym adresem to ślad zgadywania haseł. Login tak,
+    hasło NIGDY."""
+    audit_log.info("AUDYT zdarzenie=%s user=%s ip=%s",
+                   "logowanie-ok" if udane else "logowanie-odmowa",
+                   login or "-", client_ip(request))
+
+
+def audit_logout(request: Request) -> None:
+    audit_log.info("AUDYT zdarzenie=wylogowanie user=%s ip=%s",
+                   getattr(request.state, "user", "") or "-", client_ip(request))
+
+
+def install(app) -> None:
+    from app import session
+
+    _setup_audit_logging()
+
+    # Fail-closed: konta bez klucza podpisu to sesje nie do odróżnienia od
+    # podrobionych. Lepiej, żeby usługa nie wstała.
+    if auth_enabled() and not session.available():
+        raise session.SessionError(
+            "Konta demo są skonfigurowane, ale brakuje SESSION_SECRET — bez klucza "
+            "podpisu logowanie nie miałoby czym się bronić. openssl rand -hex 32")
+
+    if not auth_enabled():
+        log.warning(
+            "UWAGA: brak kont (ASTRODEMO_USERS / ASTRODEMO_PASSWORD) — astrodemo stoi OTWARTY. "
+            "Bez logowania nie ma też PULI: wszyscy pracowaliby na jednym, wspólnym "
+            "zbiorze baz, widząc nawzajem swoje wgrania."
+        )
+
+    @app.middleware("http")
+    async def _guard(request: Request, call_next):
+        if request.url.path in PUBLIC_PATHS or request.url.path.startswith(PUBLIC_PREFIXES):
+            return await call_next(request)
+
+        started = time.monotonic()
+        if _rate_limited(client_ip(request)):
+            return JSONResponse({"detail": "Zbyt wiele żądań — spróbuj za chwilę."},
+                                status_code=429, headers={"Retry-After": "60"})
+
+        user, odswiez = "", None
+        if auth_enabled():
+            user = principal(request) or ""
+            if not user:
+                from urllib.parse import quote
+
+                cel = request.url.path
+                dokad = f"?dokad={quote(cel, safe='/')}" if request.method == "GET" and cel != "/" else ""
+                return RedirectResponse(f"/logowanie{dokad}", status_code=303)
+            from app import session as _s
+
+            dane = _s.read(request.cookies.get(_s.COOKIE))
+            odswiez = _s.refresh(dane) if dane else None
+        request.state.user = user
+
+        response = await call_next(request)
+        if odswiez:
+            from app import session as _s
+
+            response.set_cookie(_s.COOKIE, odswiez, max_age=_s.max_age(),
+                                **_s.cookie_params(secure=cookies_secure()))
+        records = getattr(request.state, "audit_records", None)
+        audit_log.info(
+            "AUDYT user=%s ip=%s method=%s path=%s status=%s records=%s ms=%.0f",
+            user or "-", client_ip(request), request.method, request.url.path,
+            response.status_code, "-" if records is None else records,
+            (time.monotonic() - started) * 1000)
+        return response

services/astrodemo/app/session.py

@@ -0,0 +1,190 @@
+"""Sesje logowania — podpisane ciasteczko (LOG-34).
+
+Kopia modułu z warstwy prezentacji, tak samo jak link_crypto: usługi są osobnymi
+obrazami i nie importują się nawzajem. Różni je WYŁĄCZNIE nazwa ciasteczka.
+
+
+CO ZASTĘPUJE I DLACZEGO. HTTP Basic nie ma wylogowania: przeglądarka zapamiętuje
+hasło i dosyła je SAMA przy każdym żądaniu, więc serwer nie ma czego zapomnieć.
+Sesja odwraca tę zależność — to serwer decyduje, czy dana przeglądarka jest
+w środku, i może tę decyzję cofnąć.
+
+TRZY POZIOMY UNIEWAŻNIENIA, celowo rozdzielone, bo każdy kosztuje co innego:
+
+  1. WYLOGOWANIE = skasowanie ciasteczka. Natychmiastowe, bez żadnego magazynu,
+     działa wszędzie. To jest to, czego oczekuje człowiek klikający „Wyloguj".
+  2. ZMIANA POŚWIADCZEŃ = odcisk hasła wpisany w ciasteczko przestaje pasować.
+     Zmiana hasła albo skasowanie konta ubija jego sesje SAMO, bez pamiętania
+     o tym — i też nie wymaga magazynu.
+  3. WYLOGOWANIE ZDALNE („wyrzuć ze wszystkich urządzeń") = licznik wersji,
+     który musi gdzieś leżeć. Wymaga zapisu, więc jest opcjonalny: gdy aplikacja
+     nie poda licznika, poziomy 1 i 2 nadal działają.
+
+Poziom 2 jest tu najważniejszy: bez niego odebranie komuś dostępu przez zmianę
+hasła zostawiałoby jego otwartą sesję żywą aż do wygaśnięcia — czyli odebranie
+dostępu nie odbierałoby dostępu.
+
+KLUCZ JEST WYMAGANY i bez niego usługa się nie uruchamia. Losowanie przy starcie
+byłoby wygodne, ale oznaczałoby wylogowanie wszystkich przy każdym restarcie
+poda — co wygląda jak awaria i uczy ludzi ignorować ekran logowania.
+
+Podpis: HMAC-SHA256 ze stdlib. Bez nowych zależności — ta sama linia co scrypt
+w PRE-27 i AES w PRE-16.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import time
+
+# Nazwa własna tej usługi. Gdyby dwie aplikacje pod jedną domeną używały
+# ciasteczka o tej samej nazwie, nadpisywałyby się nawzajem i człowiek wypadałby
+# z jednej, logując się do drugiej.
+COOKIE = "astrodemo_sesja"
+
+# Twardy kres życia sesji i kres bezczynności. Oba w sekundach, oba z konfiguracji.
+DEFAULT_MAX_AGE = 30 * 24 * 3600      # 30 dni — po tylu i tak każe się zalogować
+DEFAULT_IDLE = 8 * 3600               # 8 godzin bez ruchu = koniec
+
+# Co ile odświeżamy znacznik aktywności w ciasteczku. Bez tego progu każde
+# żądanie odsyłałoby Set-Cookie, także obrazki i arkusze stylów.
+REFRESH_AFTER = 300
+
+
+class SessionError(RuntimeError):
+    """Sesje nie mogą działać — brak klucza albo klucz nie do przyjęcia."""
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.getenv(name, "") or default)
+    except ValueError:
+        return default
+
+
+def max_age() -> int:
+    return _env_int("SESSION_MAX_AGE", DEFAULT_MAX_AGE)
+
+
+def idle_timeout() -> int:
+    return _env_int("SESSION_IDLE", DEFAULT_IDLE)
+
+
+def secret() -> bytes:
+    """Klucz podpisu. Brak = wyjątek, NIE cichy losowy klucz.
+
+    Fail-closed jest tu celowe: usługa bez klucza nie umie odróżnić ważnej sesji
+    od podrobionej, więc lepiej, żeby nie wstała, niż żeby wpuszczała."""
+    raw = os.getenv("SESSION_SECRET", "").strip()
+    if not raw:
+        raise SessionError(
+            "Brak SESSION_SECRET — bez klucza podpisu sesje nie mogą działać. "
+            "Wygeneruj: openssl rand -hex 32")
+    if len(raw) < 32:
+        raise SessionError(
+            f"SESSION_SECRET ma {len(raw)} znaków — za krótki. Wymagane co najmniej 32; "
+            f"krótki klucz da się odgadnąć, a wtedy podrobienie sesji jest trywialne.")
+    return raw.encode("utf-8")
+
+
+def available() -> bool:
+    """Czy sesje da się w ogóle obsłużyć (do sprawdzenia przy starcie)."""
+    try:
+        secret()
+    except SessionError:
+        return False
+    return True
+
+
+def fingerprint(secret_spec: str) -> str:
+    """Odcisk poświadczenia konta — 16 znaków hasza z hasła (albo jego hasza).
+
+    NIE JEST to hasło ani nic, z czego da się je odtworzyć: bierzemy skrót
+    zapisanego sekretu, a ten dla kont zarządzanych sam jest już haszem scrypt.
+    Do ciasteczka trafia po to, żeby zmiana hasła albo skasowanie konta
+    unieważniły jego sesje same z siebie."""
+    return hashlib.sha256(("odcisk:" + (secret_spec or "")).encode("utf-8")).hexdigest()[:16]
+
+
+def _sign(payload: bytes) -> bytes:
+    return hmac.new(secret(), payload, hashlib.sha256).digest()
+
+
+def _b64(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
+
+
+def _unb64(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def issue(login: str, odcisk: str, wersja: int = 0, *, now: float | None = None) -> str:
+    """Nowe ciasteczko sesji dla konta."""
+    teraz = int(now if now is not None else time.time())
+    payload = json.dumps(
+        {"u": login, "f": odcisk, "v": int(wersja), "wyd": teraz, "akt": teraz},
+        separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return f"{_b64(payload)}.{_b64(_sign(payload))}"
+
+
+def read(token: str | None, *, now: float | None = None) -> dict | None:
+    """Ciasteczko → zawartość albo None, gdy cokolwiek się nie zgadza.
+
+    None znaczy „nie wpuszczać" i nie mówi dlaczego — powód jest tu bez wartości
+    dla wołającego, a rozróżnianie „zła sygnatura" od „wygasło" tylko pomaga
+    zgadywać. Wygaśnięcie i tak kończy się tym samym ekranem logowania."""
+    if not token or "." not in token:
+        return None
+    surowy, _, podpis = token.rpartition(".")
+    try:
+        payload = _unb64(surowy)
+        oczekiwany = _sign(payload)
+        podany = _unb64(podpis)
+    except (ValueError, SessionError):
+        return None
+    # Porównanie w stałym czasie: zwykłe == przecieka informację o tym, ile
+    # pierwszych bajtów podpisu się zgadza, a to wystarcza do podrobienia.
+    if not hmac.compare_digest(oczekiwany, podany):
+        return None
+    try:
+        dane = json.loads(payload.decode("utf-8"))
+        login, odcisk = str(dane["u"]), str(dane["f"])
+        wersja, wyd, akt = int(dane["v"]), int(dane["wyd"]), int(dane["akt"])
+    except (ValueError, KeyError, TypeError):
+        return None
+
+    teraz = int(now if now is not None else time.time())
+    # Ciasteczko z przyszłości oznacza przestawiony zegar albo podrobienie —
+    # w obu wypadkach nie ma powodu mu ufać.
+    if wyd > teraz + 60:
+        return None
+    if teraz - wyd > max_age() or teraz - akt > idle_timeout():
+        return None
+    return {"login": login, "odcisk": odcisk, "wersja": wersja, "wydano": wyd, "aktywnosc": akt}
+
+
+def refresh(dane: dict, *, now: float | None = None) -> str | None:
+    """Odświeżone ciasteczko, gdy znacznik aktywności zdążył się zestarzeć.
+
+    None = nie ma potrzeby nic odsyłać. Bez tego progu każde żądanie zwracałoby
+    Set-Cookie — także po arkusze stylów i obrazki."""
+    teraz = int(now if now is not None else time.time())
+    if teraz - dane["aktywnosc"] < REFRESH_AFTER:
+        return None
+    payload = json.dumps(
+        {"u": dane["login"], "f": dane["odcisk"], "v": dane["wersja"],
+         "wyd": dane["wydano"], "akt": teraz},
+        separators=(",", ":"), sort_keys=True).encode("utf-8")
+    return f"{_b64(payload)}.{_b64(_sign(payload))}"
+
+
+def cookie_params(secure: bool = True) -> dict:
+    """Ustawienia ciasteczka wspólne dla ustawiania i kasowania.
+
+    httponly — JavaScript nie ma po co go czytać, a bez tego jeden wstrzyknięty
+    skrypt wynosi sesję. samesite=strict — odcina większość ataków polegających
+    na tym, że obca strona wysyła żądanie w imieniu zalogowanego."""
+    return {"httponly": True, "samesite": "strict", "secure": secure, "path": "/"}

services/astrodemo/app/static/styles.css

@@ -0,0 +1,63 @@
+/* Arkusz CELOWO minimalny: dwa formularze i tabela wyników. Każda klasa ponad to
+   niosłaby nazwę funkcji, której tu nie ma. */
+:root {
+  --bg: #11121b; --panel: #191b26; --line: #2b2e3d;
+  --fg: #e8e9f0; --muted: #9aa0b4; --accent: #8ab4ff;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; background: var(--bg); color: var(--fg);
+  font: 15px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+main { max-width: 880px; margin: 0 auto; padding: 1.5rem 1rem 3rem; }
+.topbar { padding: .5rem 0 1rem; border-bottom: 1px solid var(--line);
+           display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; }
+.kto { display: flex; align-items: center; gap: .5rem; }
+.whoami { color: var(--muted); font-size: .85rem; }
+.wyloguj-form { display: inline; margin: 0; }
+button.wyloguj {
+  background: none; border: 1px solid var(--line); color: var(--muted);
+  font: inherit; font-weight: 400; padding: .35rem .8rem; border-radius: 8px; cursor: pointer;
+}
+button.wyloguj:hover { color: var(--fg); }
+
+/* Ekran logowania — wąski, bez niczego poza formularzem. */
+.login-card label { display: block; margin-top: .75rem; }
+.login-card input { width: 100%; }
+h1 { margin: 0; font-size: 1.4rem; letter-spacing: .5px; }
+h2 { margin: 0 0 .3rem; font-size: 1.05rem; }
+h3 { margin: 0 0 .5rem; font-size: 1rem; }
+
+.card {
+  margin-top: 1.25rem; padding: 1rem 1.25rem;
+  background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
+}
+.row { display: flex; gap: .75rem; flex-wrap: wrap; align-items: flex-end; margin-top: .6rem; }
+label { display: flex; flex-direction: column; gap: .25rem; color: var(--muted); font-size: .85rem; flex: 1; min-width: 10rem; }
+input {
+  width: 100%; padding: .45rem .6rem; background: #0e0f18; color: var(--fg);
+  border: 1px solid var(--line); border-radius: 8px; font: inherit;
+}
+button {
+  padding: .5rem 1.25rem; background: var(--accent); color: #10121a;
+  border: none; border-radius: 8px; font: inherit; font-weight: 600; cursor: pointer;
+}
+
+table { width: 100%; border-collapse: collapse; margin-top: .3rem; }
+td { padding: .35rem .5rem; border-bottom: 1px solid var(--line); vertical-align: top; font-size: .92rem; }
+td.key { color: var(--accent); white-space: nowrap; padding-right: 1rem; }
+tr:last-child td { border-bottom: none; }
+
+.sig { margin-top: .75rem; }
+.sig-head { color: var(--muted); font-size: .85rem; }
+.meta { color: var(--muted); margin: 1.5rem 0 .5rem; font-size: .9rem; }
+.muted { color: var(--muted); }
+.small { font-size: .85rem; }
+.foot { margin-top: 2.5rem; color: var(--muted); font-size: .8rem; }
+
+.alert, .ok {
+  margin: 1rem 0; padding: .6rem .9rem; border-radius: 8px; font-size: .92rem;
+  border: 1px solid var(--line); border-left-width: 4px;
+}
+.alert { border-left-color: #b8860b; background: rgba(184, 134, 11, .1); }
+.ok { border-left-color: var(--accent); background: rgba(138, 180, 255, .08); }

services/astrodemo/app/templates/base.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="pl">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>astrodemo · {% block title %}{% endblock %}</title>
+  <link rel="stylesheet" href="/static/styles.css">
+</head>
+<body>
+  <main>
+    <header class="topbar">
+      <h1>astrodemo</h1>
+      {# Kto jest zalogowany i wyjście. Demo bywa używane na cudzych komputerach,
+         więc bez tego pierwszy klient zostawia otwartą sesję drugiemu. #}
+      {% if auth_on() %}
+      <div class="kto">
+        <span class="whoami">{{ current_user(request) }}</span>
+        <form method="post" action="/wyloguj" class="wyloguj-form">
+          <button type="submit" class="wyloguj">Wyloguj</button>
+        </form>
+      </div>
+      {% endif %}
+      {# CELOWO BEZ NAWIGACJI. Dwie funkcje mieszczą się na jednym ekranie,
+         a pasek zakładek z jedną pozycją tylko sugerowałby, że są inne. #}
+    </header>
+    {% block content %}{% endblock %}
+    <footer class="foot">wersja demonstracyjna</footer>
+  </main>
+</body>
+</html>

services/astrodemo/app/templates/index.html

@@ -0,0 +1,87 @@
+{% extends "base.html" %}
+{% block title %}Interpretacja{% endblock %}
+
+{% block content %}
+{% if error %}<p class="alert">{{ error }}</p>{% endif %}
+{% if done %}<p class="ok">{{ done }}</p>{% endif %}
+
+<section class="card">
+  <h2>Dodaj bazę</h2>
+  <p class="muted small">
+    Wgrany plik zaczyna być używany od razu przy wyszukiwaniu interpretacji.
+  </p>
+  <form method="post" action="/plik" enctype="multipart/form-data">
+    <div class="row">
+      <label>Plik <input type="file" name="upload" required></label>
+      <button type="submit">Dodaj</button>
+    </div>
+  </form>
+</section>
+
+<section class="card">
+  <h2>Zapytaj o interpretację urodzeniową</h2>
+  <form method="post" action="/">
+    <div class="row">
+      <label>Data urodzenia
+        <input type="date" name="date" value="{{ form.date or '' }}" required></label>
+      <label>Godzina (lokalna)
+        <input type="time" name="time" value="{{ form.time or '' }}" required></label>
+      <label>Offset względem GMT (h)
+        <input type="number" name="tz_offset" step="0.5" value="{{ form.tz_offset if form.tz_offset is not none else 0 }}"></label>
+    </div>
+    <div class="row">
+      <label>Szerokość (lat, + N)
+        <input type="number" name="lat" step="0.0001" value="{{ form.lat if form.lat is not none else 0 }}" required></label>
+      <label>Długość (lon, + E)
+        <input type="number" name="lon" step="0.0001" value="{{ form.lon if form.lon is not none else 0 }}" required></label>
+      <button type="submit">Szukaj interpretacji</button>
+    </div>
+  </form>
+</section>
+
+{% if result %}
+  <p class="meta">
+    Moment: <strong>{{ moment }}</strong>
+    {% if result.engine %}· silnik: {{ result.engine }}{% endif %}
+    {% if result.objects %}· obiektów: {{ result.objects | length }}{% endif %}
+  </p>
+
+  {# Kształt odpowiedzi: objects[] → facets[] → samples[]. Pytamy bez grupowania,
+     więc `groups` tu nie wystąpi i nie ma czego obsługiwać. #}
+  {% set znaleziono = namespace(ile=0) %}
+  {% for o in result.objects or [] %}
+    {% set trafienia = o.facets | selectattr('samples') | list %}
+    {% if trafienia %}
+      {% set znaleziono.ile = znaleziono.ile + trafienia | length %}
+      <section class="card">
+        <h3>{{ o.object }}
+          <span class="muted">w {{ o.sign }}{% if o.house %}, {{ o.house }}. dom{% endif %}
+            {%- if o.direction == 'Rx' %} · Rx{% endif %}</span>
+        </h3>
+        {% for f in trafienia %}
+        <div class="sig">
+          <div class="sig-head">{{ f.label }} <span class="muted small">— {{ f.count }} dopasowań</span></div>
+          <table>
+            <tbody>
+              {% for s in f.samples %}
+              <tr>
+                <td class="key" title="{{ s.significator }}">{{ s.expanded }}</td>
+                <td>{{ s.effect }}</td>
+              </tr>
+              {% endfor %}
+            </tbody>
+          </table>
+        </div>
+        {% endfor %}
+      </section>
+    {% endif %}
+  {% endfor %}
+
+  {% if znaleziono.ile == 0 %}
+    <p class="muted">
+      Nie znaleziono interpretacji dla tych danych. Sprawdź, czy dodano bazę
+      zawierającą pasujące opisy.
+    </p>
+  {% endif %}
+{% endif %}
+{% endblock %}

services/astrodemo/app/templates/logowanie.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="pl">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>astrodemo · logowanie</title>
+  <link rel="stylesheet" href="/static/styles.css">
+</head>
+<body>
+  <main class="login-main">
+    <header class="topbar"><h1>astrodemo</h1></header>
+
+    {% if request.query_params.get('wylogowano') %}
+      <p class="ok">Wylogowano.</p>
+    {% endif %}
+    {% if blad %}<p class="alert">{{ blad }}</p>{% endif %}
+
+    <form method="post" action="/logowanie" class="card login-card">
+      {# Adres powrotu jedzie w ukrytym polu, ale i tak przechodzi przez sito
+         po stronie serwera — pole formularza jest wejściem od użytkownika. #}
+      <input type="hidden" name="dokad" value="{{ dokad }}">
+      <label>Login
+        <input type="text" name="login" value="{{ login or '' }}" required
+               autocomplete="username" autofocus></label>
+      <label>Hasło
+        <input type="password" name="haslo" required autocomplete="current-password"></label>
+      <div class="actions"><button type="submit">Zaloguj</button></div>
+    </form>
+
+    <p class="muted small login-note">
+      Nie masz konta albo nie pamiętasz hasła? Zgłoś się do osoby, która zakładała
+      Ci dostęp — kont nie da się odzyskać samodzielnie.
+    </p>
+  </main>
+</body>
+</html>

services/astrodemo/requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8.0

services/astrodemo/requirements.txt

@@ -0,0 +1,11 @@
+# CELOWO KRÓTSZA niż w warstwie prezentacji. Astroklient ma dwie funkcje, więc nie
+# potrzebuje ani Excela (brak eksportu), ani stref czasowych z lokalizacji (offset
+# podaje się wprost), ani niczego pod kosmogram — a każda zbędna zależność w obrazie
+# demo to kolejna rzecz do pilnowania i kolejna droga do środka.
+fastapi>=0.115
+uvicorn[standard]>=0.34
+httpx>=0.28
+jinja2>=3.1
+python-multipart>=0.0.20
+# Szyfrowanie łącza do warstwy logicznej (PRE-16): AES-256-GCM + HKDF
+cryptography>=44.0

services/astrodemo/tests/test_astrodemo.py

@@ -0,0 +1,301 @@
+"""astrodemo — wersja demonstracyjna (PRE-28).
+
+DWIE WŁASNOŚCI, KTÓRYCH PILNUJE TEN PLIK
+
+1. Demo ma DWIE funkcje i ani jednej więcej. Sprawdzamy to na trasach aplikacji,
+   nie w szablonie: trasa, o której nikt nie pamiętał, jest tu realnym ryzykiem,
+   bo ta usługa rozmawia z warstwą danych produkcji.
+
+2. „Dodać plik do bazy" znaczy, że plik ZACZYNA BYĆ UŻYWANY. W pełnej aplikacji
+   wgranie i włączenie to dwie decyzje (DAN-27); tutaj muszą być jedną, inaczej
+   po wgraniu nic się nie zmienia i demo wygląda na zepsute.
+"""
+import base64
+
+import pytest
+
+from app import security
+
+
+@pytest.fixture()
+def env(monkeypatch):
+    monkeypatch.setenv("ASTRODEMO_USERS", "demo:tajne-demo,klientA:hasloA,klientB:hasloB")
+    monkeypatch.delenv("ASTRODEMO_USER", raising=False)
+    monkeypatch.delenv("ASTRODEMO_PASSWORD", raising=False)
+    monkeypatch.setenv("RATE_LIMIT_PER_MIN", "0")
+    # Bez klucza podpisu usługa celowo nie wstaje (fail-closed, LOG-34).
+    monkeypatch.setenv("SESSION_SECRET", "t" * 64)
+    monkeypatch.setenv("COOKIES_INSECURE", "1")      # TestClient jedzie po http
+
+
+def _auth(user="demo", password=""):
+    """Nagłówek z WAŻNĄ SESJĄ — odpowiednik bycia zalogowanym.
+
+    Po przejściu z Basic na sesje (LOG-34) „zalogowany" znaczy „ma podpisane
+    ciasteczko", nie „ma nagłówek z hasłem". Hasło przyjmowane tylko po to, żeby
+    nie przepisywać wszystkich wywołań — sprawdzanie poświadczeń ma własne testy."""
+    from app import security, session
+
+    return {"Cookie": f"{session.COOKIE}={security.issue_session(user)}"}
+
+
+REPORT = {
+    "engine": "test",
+    "objects": [{
+        "object": "Sun", "sign": "Taurus", "house": 11, "direction": "D",
+        "planet_token": "Su", "planet_total": 3,
+        "facets": [{"label": "w znaku Taurus", "token": "Su Tau", "count": 1, "score": 5.0,
+                    "samples": [{"significator": "Su Tau", "expanded": "Sun in Taurus",
+                                 "effect": "wytrwały, praktyczny"}]}],
+    }],
+}
+
+
+def _client(monkeypatch, calls=None, upload=None):
+    """Podmieniamy METODY KLASY, nie obiekt modułowy: klient jest budowany per
+    żądanie, żeby pula wynikała z zalogowanego konta. Dzięki temu podglądamy
+    też `self.tenant`, czyli to, do której puli faktycznie poszło zapytanie."""
+    from starlette.testclient import TestClient
+
+    from app.clients.logic_client import LogicClient
+    from app.main import app
+
+    calls = calls if calls is not None else []
+    domyslny = {"path": "nowa.xlsx", "name": "nowa.xlsx", "accepted": True}
+
+    monkeypatch.setattr(LogicClient, "report",
+                        lambda self, **kw: (calls.append(("report", self.tenant, kw)), REPORT)[1])
+    monkeypatch.setattr(LogicClient, "files_upload",
+                        lambda self, *a, **kw: (calls.append(("upload", self.tenant, a)),
+                                                upload or domyslny)[1])
+    monkeypatch.setattr(LogicClient, "files_status",
+                        lambda self, *a, **kw: (calls.append(("status", self.tenant, a)), {})[1])
+    return TestClient(app), calls
+
+
+FORM = {"date": "1984-04-30", "time": "11:20", "tz_offset": "2",
+        "lat": "50.06", "lon": "19.94"}
+
+
+# ── powierzchnia: dokładnie dwie funkcje ────────────────────────────────
+
+def test_the_service_exposes_nothing_beyond_its_two_functions():
+    """Trasa, o której nikt nie pamiętał, jest tu realnym ryzykiem — ta usługa
+    rozmawia z warstwą danych PRODUKCJI."""
+    from app.main import app
+
+    trasy = {(m, r.path) for r in app.routes for m in (getattr(r, "methods", None) or set())
+             if not r.path.startswith("/static") and m in {"GET", "POST"}}
+    assert trasy == {("GET", "/"), ("POST", "/"), ("POST", "/plik"), ("GET", "/health"),
+                     ("GET", "/logowanie"), ("POST", "/logowanie"), ("POST", "/wyloguj")}
+
+
+def test_the_client_can_only_ask_for_what_the_demo_needs():
+    """Klient warstwy logicznej jest okrojony CELOWO: metody, której nie ma, nikt
+    przypadkiem nie zawoła i nie podpowie ona, że po drugiej stronie jest więcej."""
+    from app.clients.logic_client import LogicClient
+
+    publiczne = {n for n in dir(LogicClient) if not n.startswith("_")}
+    assert publiczne == {"report", "files_upload", "files_status", "health"}
+
+
+def test_api_docs_are_off():
+    """/docs wypisałoby komplet tras — demo ma nie zdradzać własnej powierzchni."""
+    from app.main import app
+
+    assert app.docs_url is None and app.openapi_url is None and app.redoc_url is None
+
+
+# ── logowanie ────────────────────────────────────────────────────────────
+
+def test_without_credentials_nothing_is_served(env, monkeypatch):
+    c, _ = _client(monkeypatch)
+    for method, path in (("get", "/"), ("post", "/"), ("post", "/plik")):
+        r = getattr(c, method)(path, follow_redirects=False)
+        assert r.status_code == 303, path
+        assert "/logowanie" in r.headers["location"], path
+    assert c.get("/health").status_code == 200, "sonda musi działać bez hasła"
+
+
+def test_demo_account_is_separate_from_the_main_application(env, monkeypatch):
+    """Konto astrodemo MUSI być własne: demo pracuje na tej samej warstwie
+    danych co produkcja, więc odcięcie go nie może wymagać zmiany haseł
+    w głównej aplikacji."""
+    monkeypatch.setenv("APP_USER", "astrololo")
+    monkeypatch.setenv("APP_PASSWORD", "haslo-glownej-aplikacji")
+    c, _ = _client(monkeypatch)
+    assert security.verify("astrololo", "haslo-glownej-aplikacji") is None
+    assert security.verify("demo", "tajne-demo") == "demo"
+
+
+def test_a_password_with_polish_letters_is_refused_not_crashed(env, monkeypatch):
+    monkeypatch.setenv("ASTRODEMO_USERS", "demo:zażółć-gęślą")
+    c, _ = _client(monkeypatch)
+
+
+
+# ── funkcja 1: dodanie pliku ─────────────────────────────────────────────
+
+def test_adding_a_file_uploads_AND_switches_it_on(env, monkeypatch):
+    """Sedno wymagania: jedna czynność, nie dwie."""
+    c, calls = _client(monkeypatch)
+    r = c.post("/plik", headers=_auth(), follow_redirects=False,
+               files={"upload": ("baza.xlsx", b"zawartosc", "application/vnd.ms-excel")})
+    assert r.status_code == 303
+    rodzaje = [k[0] for k in calls]
+    assert rodzaje == ["upload", "status"], f"oczekiwano wgrania i włączenia, było: {rodzaje}"
+    assert calls[1][2][1] == "active", "plik nie został włączony do użytku"
+
+
+def test_a_rejected_file_is_not_switched_on_and_the_reason_stays_hidden(env, monkeypatch):
+    """Walidacja zostaje, ale jej REGUŁY zna wyłącznie administrator (DAN-27) —
+    demo nie ma prawa ich zdradzić, nawet mimochodem."""
+    from urllib.parse import unquote_plus
+
+    c, calls = _client(monkeypatch, upload={"path": "zla.xlsx", "name": "zla.xlsx",
+                                            "accepted": False})
+    r = c.post("/plik", headers=_auth(), follow_redirects=False,
+               files={"upload": ("zla.xlsx", b"x", "text/plain")})
+    assert r.status_code == 303
+    assert [k[0] for k in calls] == ["upload"], "odrzucony plik został włączony do użytku"
+    komunikat = unquote_plus(r.headers["location"])
+    for slowo in ("walidacj", "reguł", "kolumn", "rozszerzeni", "rozmiar"):
+        assert slowo not in komunikat, f"komunikat zdradza mechanizm: „{slowo}”"
+
+
+def test_an_empty_file_is_refused_before_anything_is_sent(env, monkeypatch):
+    c, calls = _client(monkeypatch)
+    r = c.post("/plik", headers=_auth(), follow_redirects=False,
+               files={"upload": ("pusty.xlsx", b"", "application/vnd.ms-excel")})
+    assert r.status_code == 303 and calls == []
+
+
+# ── funkcja 2: interpretacja urodzeniowa ────────────────────────────────
+
+def test_asking_for_an_interpretation_returns_the_matches(env, monkeypatch):
+    c, calls = _client(monkeypatch)
+    r = c.post("/", headers=_auth(), data=FORM)
+    assert r.status_code == 200
+    assert "Sun in Taurus" in r.text and "wytrwały, praktyczny" in r.text
+    assert [k[0] for k in calls] == ["report"]
+
+
+def test_local_time_is_converted_to_utc_before_asking(env, monkeypatch):
+    """11:20 przy offsecie +2 to 09:20 UTC. Pomyłka tutaj przesuwa CAŁY horoskop,
+    a wynik nadal wygląda wiarygodnie — dlatego sprawdzamy wprost."""
+    c, calls = _client(monkeypatch)
+    c.post("/", headers=_auth(), data=FORM)
+    assert calls[0][2]["when_utc_iso"].startswith("1984-04-30T09:20")
+
+
+def test_a_malformed_date_is_explained_not_thrown(env, monkeypatch):
+    c, calls = _client(monkeypatch)
+    r = c.post("/", headers=_auth(), data={**FORM, "date": "30 kwietnia"})
+    assert r.status_code == 200 and "RRRR-MM-DD" in r.text
+    assert calls == [], "poszło zapytanie mimo błędnych danych"
+
+
+def test_a_broken_logic_layer_is_reported_not_crashed(env, monkeypatch):
+    import httpx
+
+    from app.clients.logic_client import LogicClient
+
+    c, _ = _client(monkeypatch)
+    monkeypatch.setattr(LogicClient, "report", lambda self, **kw: (_ for _ in ()).throw(
+        httpx.ConnectError("brak połączenia")))
+    r = c.post("/", headers=_auth(), data=FORM)
+    # Komunikat jest CELOWO nieinformacyjny: treść wyjątku niosła nazwę usługi,
+    # jej port i nazwy tras, czyli mapę tego, co stoi za tym ekranem.
+    assert r.status_code == 200
+    assert "Nie udało się teraz wykonać tej operacji" in r.text
+    assert "Warstwa logiczna" not in r.text and "8001" not in r.text
+
+
+def test_the_page_never_offers_anything_it_cannot_do(env, monkeypatch):
+    """Demo ma wyglądać na KOMPLETNE w swojej postaci — żadnych śladów funkcji,
+    których nie ma (ta sama zasada, co przy uprawnieniach w PRE-27)."""
+    c, _ = _client(monkeypatch)
+    html = c.get("/", headers=_auth()).text
+    for slowo in ("Kosmogram", "Synastria", "Kalendarz", "Skompiluj", "Ustawienia",
+                  "Konta", "PDF", "Excel", "prompt", "model"):
+        assert slowo not in html, f"strona wspomina o „{slowo}”, czego demo nie umie"
+
+
+# ── pule kont: izolacja (PRE-29) ─────────────────────────────────────────
+# Demo jest udostępniane szeroko i różnym osobom, więc pula musi wynikać
+# z tego, KTO SIĘ ZALOGOWAŁ — i z niczego innego. Wyciek byłby cichy: klient
+# zobaczyłby cudze bazy jako własne.
+
+def test_the_pool_is_taken_from_the_login(env, monkeypatch):
+    c, calls = _client(monkeypatch)
+    c.post("/", headers=_auth("klientA", "hasloA"), data=FORM)
+    c.post("/", headers=_auth("klientB", "hasloB"), data=FORM)
+    assert [k[1] for k in calls] == ["klientA", "klientB"]
+
+
+def test_uploads_go_to_the_pool_of_the_account_that_sent_them(env, monkeypatch):
+    c, calls = _client(monkeypatch)
+    c.post("/plik", headers=_auth("klientA", "hasloA"), follow_redirects=False,
+           files={"upload": ("baza.xlsx", b"x", "application/vnd.ms-excel")})
+    assert {k[1] for k in calls} == {"klientA"}, "wgranie trafiło do cudzej puli"
+
+
+def test_the_pool_cannot_be_chosen_from_the_form(env, monkeypatch):
+    """Gdyby pula przychodziła z żądania, wystarczyłoby podstawić cudzy login."""
+    c, calls = _client(monkeypatch)
+    c.post("/", headers=_auth("klientA", "hasloA"),
+           data={**FORM, "tenant": "klientB", "user": "klientB", "login": "klientB"})
+    assert [k[1] for k in calls] == ["klientA"], "pula dała się podmienić z formularza"
+
+
+def test_every_account_has_its_own_pool_by_construction(env, monkeypatch):
+    """Każdy login = inna pula. Dwa konta nie mogą dzielić zbioru baz."""
+    c, calls = _client(monkeypatch)
+    for login, haslo in (("demo", "tajne-demo"), ("klientA", "hasloA"), ("klientB", "hasloB")):
+        c.post("/", headers=_auth(login, haslo), data=FORM)
+    pule = [k[1] for k in calls]
+    assert len(set(pule)) == len(pule) == 3
+
+
+def test_an_unknown_account_gets_nothing(env, monkeypatch):
+    """Bez ważnej sesji żądanie nie schodzi niżej — nie wystarczy, że skończy
+    się przekierowaniem: nie może po drodze dotknąć warstwy logicznej."""
+    c, calls = _client(monkeypatch)
+    r = c.post("/", data=FORM, follow_redirects=False)
+    assert r.status_code == 303 and "/logowanie" in r.headers["location"]
+    assert calls == [], "poszło zapytanie mimo braku sesji"
+
+
+def test_logging_in_and_out_of_the_demo(env, monkeypatch):
+    """Pełny obieg: demo bywa używane na cudzych komputerach, więc wyjście musi
+    naprawdę kończyć sesję, a nie tylko tak wyglądać."""
+    from app import session
+
+    c, _ = _client(monkeypatch)
+    r = c.post("/logowanie", follow_redirects=False,
+               data={"login": "klientA", "haslo": "hasloA", "dokad": "/"})
+    assert r.status_code == 303 and session.COOKIE in r.cookies
+
+    wyjscie = c.post("/wyloguj", headers=_auth("klientA"), follow_redirects=False)
+    assert wyjscie.status_code == 303
+    ustawione = wyjscie.headers.get("set-cookie", "")
+    assert session.COOKIE in ustawione and "Max-Age=0" in ustawione
+
+
+def test_removing_an_account_kills_its_open_session(env, monkeypatch):
+    """Demo nie ma gdzie trwale zapisywać stanu, więc zdalne unieważnienie robi
+    się przez ASTRODEMO_USERS — usunięcie albo zmiana hasła ubija sesję odciskiem."""
+    c, _ = _client(monkeypatch)
+    ciasteczko = _auth("klientA")
+    assert c.get("/", headers=ciasteczko, follow_redirects=False).status_code == 200
+
+    monkeypatch.setenv("ASTRODEMO_USERS", "demo:tajne-demo,klientB:hasloB")   # bez klientA
+    assert c.get("/", headers=ciasteczko, follow_redirects=False).status_code == 303
+
+
+def test_the_demo_login_cannot_be_turned_into_a_redirector(env, monkeypatch):
+    c, _ = _client(monkeypatch)
+    for zly in ("https://obcy.pl", "//obcy.pl", "http://obcy.pl/x"):
+        r = c.post("/logowanie", follow_redirects=False,
+                   data={"login": "demo", "haslo": "tajne-demo", "dokad": zly})
+        assert r.headers["location"] == "/", f"przepuszczono: {zly}"

services/astrodemo/tests/test_slownik_zakazany.py

@@ -0,0 +1,192 @@
+"""Zapora słownikowa astrodemo: czego użytkownik demo nie może zobaczyć.
+
+astrodemo stoi najniżej w drabinie trzech produktów (astrodemo → astroklient →
+astrololo) i jest dawane najszerzej. Ma dwie funkcje i ma wyglądać, jakby to
+było wszystko, co program potrafi.
+
+Test nie sprawdza pojedynczych miejsc, tylko przechodzi WSZYSTKO, co da się
+pobrać, i szuka słów, które nie mają prawa paść. Sprawdza też DRZEWO PLIKÓW
+usługi — bo „nie ma śladu w kodzie" znaczy, że `grep` po obrazie ma nic nie
+znaleźć, a nie tylko że odpowiedź jest czysta.
+
+Powód, dla którego to powstało: komentarz w pierwszej linii styles.css mówił
+„Nie kopiujemy stylów pełnej aplikacji", a arkusz pobierał anonim.
+"""
+import pathlib
+import re
+
+import pytest
+
+APP = pathlib.Path(__file__).resolve().parents[1] / "app"
+
+# (a) że istnieje wersja obszerniejsza i jak się nazywa
+WIEKSZY_BRAT = ["pełna aplikacja", "pełnej aplikacji", "pełna wersja", "pełnej wersji",
+                "astrololo", "astroklient", "wersji podstawowej", "upgrade", "rozszerzon"]
+# (b) że tekst pisze model językowy
+# Bez samego „token": w tej usłudze znaczy token sesji i token międzywarstwowy,
+# a nie jednostkę rozliczeniową modelu. Zamiast tego zwroty jednoznaczne.
+MODEL = ["LLM", "anthropic", "openai", "gpt", "claude", "prompt",
+         "generowanie tekstu", "sztuczn", "okno kontekstu", "model językow"]
+# (c) funkcje, których astrodemo nie ma
+INNE_FUNKCJE = ["kosmogram", "aspektarian", "synastri", "kalendarz", "predykcj",
+                "skompiluj", "system domów", "systemy domów", "deklinacj", "antyscj"]
+# (d) że jest ktoś, kto widzi więcej, i że produkt jest w budowie
+MECHANIZMY = ["administrator", "uprawnieni", "walidacj", "kwarantann", "roadmap",
+              "w budowie", "widok testowy", "warstwa logiczna", "layer"]
+# Dwa poziomy, bo dwie różne drogi wycieku.
+#
+# WSZĘDZIE — także w kodzie serwera, którego przeglądarka nigdy nie zobaczy.
+# Obraz tej usługi się KOMUŚ ODDAJE, więc kto go dostanie, przeczyta też
+# komentarze i docstringi. Zdanie „w pełnej aplikacji to działa inaczej" mówi mu
+# wprost, że istnieje pełna aplikacja — a to jest dokładnie to, czego ma nie
+# wiedzieć. Komentarz ma tłumaczyć TĘ usługę, bez powoływania się na rodzeństwo.
+WSZEDZIE = WIEKSZY_BRAT + MODEL + INNE_FUNKCJE
+# TYLKO DO PRZEGLĄDARKI — słownictwo inżynierskie opisujące własne działanie tej
+# usługi. W komentarzu serwera jest na miejscu; w odpowiedzi HTTP nie ma czego
+# szukać, bo mówi o mechanizmach, o których użytkownik nie ma wiedzieć.
+DO_PRZEGLADARKI = WSZEDZIE + MECHANIZMY
+ZAKAZANE = DO_PRZEGLADARKI
+WZORCE = [(r"(?i)\b(PRE|LOG|DAN)-\d+\b", "identyfikator wymagania"),
+          (r"(?i)\bfeat/[\w-]+", "nazwa gałęzi rozwojowej"),
+          (r"(?i)\bAI\b", "model językowy")]
+
+
+def _grzechy(tresc: str, gdzie: str, slownik: list[str] | None = None) -> list[str]:
+    out = []
+    for igla in (slownik if slownik is not None else ZAKAZANE):
+        if re.search(rf"(?i)(?<![\w-]){re.escape(igla)}", tresc):
+            out.append(f"{gdzie}: „{igla}”")
+    for wzor, powod in (WZORCE if slownik is None else WZORCE[-1:]):
+        m = re.search(wzor, tresc)
+        if m:
+            out.append(f"{gdzie}: „{m.group(0)}” — {powod}")
+    return out
+
+
+@pytest.fixture()
+def klient(monkeypatch):
+    monkeypatch.setenv("ASTRODEMO_USERS", "demo:tajne-demo")
+    monkeypatch.setenv("SESSION_SECRET", "t" * 64)
+    monkeypatch.setenv("COOKIES_INSECURE", "1")
+    monkeypatch.setenv("RATE_LIMIT_PER_MIN", "0")
+    from starlette.testclient import TestClient
+
+    from app.main import app
+
+    return TestClient(app, follow_redirects=False)
+
+
+def test_nothing_forbidden_reaches_an_anonymous_visitor(klient):
+    grzechy, obejrzane = [], 0
+    for adres in ("/logowanie", "/health", "/static/styles.css"):
+        r = klient.get(adres)
+        assert r.status_code == 200, f"{adres}: {r.status_code}"
+        obejrzane += 1
+        grzechy += _grzechy(r.text, adres)
+    assert obejrzane == 3
+    assert not grzechy, "\n" + "\n".join(grzechy)
+
+
+def test_nothing_forbidden_reaches_a_logged_in_visitor(klient, monkeypatch):
+    from app import security, session
+
+    naglowki = {"Cookie": f"{session.COOKIE}={security.issue_session('demo')}"}
+    # Warstwa logiczna niedostępna CELOWO: ekran idzie wtedy ścieżką błędu,
+    # a to komunikaty o awarii wypisywały nazwy warstw i tras.
+    import httpx
+
+    from app.main import LogicClient
+
+    monkeypatch.setattr(LogicClient, "report",
+                        lambda *a, **k: (_ for _ in ()).throw(httpx.ConnectError("nie da rady")))
+    grzechy = []
+    for adres in ("/", "/static/styles.css"):
+        r = klient.get(adres, headers=naglowki)
+        assert r.status_code == 200, f"{adres}: {r.status_code}"
+        grzechy += _grzechy(r.text, adres)
+    r = klient.post("/", headers=naglowki,
+                    data={"date": "1984-04-30", "time": "11:20", "tz_offset": "2",
+                          "lat": "50.06", "lon": "19.94"})
+    grzechy += _grzechy(r.text, "POST /")
+    assert not grzechy, "\n" + "\n".join(grzechy)
+
+
+# Stałe protokołu łącza (nagłówki, typ treści, etykieta HKDF) niosą nazwę rodziny
+# produktów, ale są WSPÓLNE z warstwą logiczną: zmiana wymaga jednoczesnej zmiany
+# we wszystkich usługach i rotacji, więc to osobna decyzja. Nie idą do przeglądarki.
+BEZ_KONTROLI = {"app/link_crypto.py"}
+
+
+def test_the_source_tree_itself_carries_no_trace():
+    """„Bez śladu w kodzie" znaczy: grep po obrazie ma nic nie znaleźć.
+
+    Odpowiedź może być czysta, a plik i tak nieść komentarz — dokładnie tak
+    wyciekał arkusz stylów, zanim komentarze zaczęły być zdejmowane."""
+    # Identyfikatory wymagań (PRE-28, LOG-34) zostają: to notatki inżynierskie
+    # o tej usłudze, nie informacja o istnieniu czegoś większego.
+    grzechy = []
+    for f in APP.rglob("*"):
+        wzgledna = str(f.relative_to(APP.parent))
+        if (not f.is_file() or "__pycache__" in str(f) or f.suffix == ".pyc"
+                or wzgledna in BEZ_KONTROLI):
+            continue
+        try:
+            grzechy += _grzechy(f.read_text(encoding="utf-8"),
+                                str(f.relative_to(APP.parent)), WSZEDZIE)
+        except UnicodeDecodeError:
+            continue
+    assert not grzechy, "\n" + "\n".join(grzechy)
+
+
+def test_an_unknown_asset_is_indistinguishable_from_one_that_never_existed(klient):
+    from app import security, session
+
+    naglowki = {"Cookie": f"{session.COOKIE}={security.issue_session('demo')}"}
+    nieistniejacy = klient.get("/static/nie-ma-takiego.js", headers=naglowki)
+    for adres in ("/static/main.py", "/static/../app/config.py", "/static/vendor/cokolwiek.js"):
+        r = klient.get(adres, headers=naglowki)
+        assert r.status_code == nieistniejacy.status_code == 404, f"{adres}: {r.status_code}"
+        assert r.text == nieistniejacy.text
+
+
+def test_the_protocol_constants_are_the_one_known_exception():
+    """Świadomie zostawiona dziura — opisana, żeby nie była przypadkiem.
+
+    Stałe łącza międzywarstwowego (`X-Astrololo-Token`, `X-Astrololo-Enc`, typ
+    treści, etykieta HKDF) niosą nazwę rodziny produktów. Są WSPÓLNE z warstwą
+    logiczną, więc zmiana wymaga jednoczesnej podmiany we wszystkich usługach
+    i rotacji sekretów — to osobna decyzja, nie efekt uboczny tej zmiany.
+
+    Warunek, pod jakim to zostaje: te stałe nie mają prawa dotrzeć do
+    przeglądarki. Idą wyłącznie w nagłówkach żądań DO warstwy logicznej.
+    Ten test pilnuje właśnie tego warunku, a nie samego istnienia stałych.
+    """
+    rdzen = "astrololo"
+    protokol = [f for f in APP.rglob("*.py")
+                if f.is_file() and rdzen in f.read_text(encoding="utf-8").lower()]
+    assert protokol, "stałe zniknęły — jeśli je przemianowano, ten wyjątek jest zbędny"
+    for f in protokol:
+        tresc = f.read_text(encoding="utf-8").lower()
+        for linia in tresc.splitlines():
+            if rdzen not in linia:
+                continue
+            # Każde wystąpienie musi być stałą protokołu albo nazwą kanału logów —
+            # nigdy tekstem, który mógłby trafić do szablonu.
+            assert any(z in linia for z in ("x-astrololo", "vnd.astrololo",
+                                            "astrololo/link/", 'getlogger("astrololo')), \
+                f"{f.name}: „{linia.strip()[:70]}” to nie jest stała protokołu"
+
+
+def test_only_the_application_code_ships_in_the_image():
+    """Obraz nie może wieźć tego testu.
+
+    Ironia, którą łatwo przeoczyć: plik pilnujący, żeby pewne słowa nie padły,
+    sam je wypisuje — więc gdy trafi do obrazu, staje się tym wyciekiem, przed
+    którym broni. `COPY . .` wnosiło cały katalog usługi, razem z tests/.
+    """
+    # Same instrukcje, bez komentarzy: komentarz obok tej linii CYTUJE dawną
+    # postać, więc szukanie po całym pliku zgłaszałoby własne wyjaśnienie.
+    instrukcje = [l for l in (APP.parent / "Dockerfile").read_text(encoding="utf-8").splitlines()
+                  if l.strip() and not l.lstrip().startswith("#")]
+    assert not any(l.strip() == "COPY . ." for l in instrukcje), "obraz wnosi wszystko, w tym testy"
+    assert any(l.strip() == "COPY app ./app" for l in instrukcje)

services/data/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8002
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8002"]

services/data/README.md

@@ -0,0 +1,46 @@
+# Warstwa bazodanowa (`data`)
+
+Niezależna usługa. **Jedyne zadanie:** wyszukać dane i podać je w górę. Nie zna
+warstwy logicznej ani prezentacji — komunikacja wyłącznie przez HTTP/JSON
+(`models.py`).
+
+## API
+- `POST /search` → `SearchQuery` → `SearchResult`
+- `GET /health` → `HealthInfo`
+
+## Architektura wewnętrzna
+```
+providers/        wymienna implementacja (wzorzec Repository)
+  base.py         interfejs DataProvider  ← kontrakt
+  excel_provider  dziś: Excel + 4 poziomy cache
+  sql_provider    jutro: SQL (ten sam interfejs)
+  factory.py      DATA_PROVIDER=excel|sql
+excel/            wykrywanie nagłówka + mapowanie układu kolumn (jedyne miejsce znające .xlsx)
+cache/            fingerprint, schema(L1), frame/parquet(L2), query(L3), index(L4)
+ingest/           build_index.py (warmup), to_sql.py (migracja ETL)
+```
+
+## Cache — dlaczego szybko
+| Poziom | Co cache'uje | Zysk |
+|-------|---------------|------|
+| L1 `schema.db` | wykryty nagłówek + układ kolumn per plik | brak ponownego skanu heurystyką |
+| L2 Parquet | znormalizowany arkusz | 10–100× szybciej niż parsowanie `.xlsx` |
+| L3 `QueryCache` | wynik zapytania (TTL/LRU) | powtarzalne zapytania natychmiast |
+| L4 `index.db` | odwrócony indeks wartość→plik | otwieramy tylko trafione pliki, nie setki |
+
+Unieważnianie: klucz = odcisk pliku (`mtime+rozmiar`, opcjonalnie `sha256`).
+Zmiana pliku → inny odcisk → automatyczny przebudowa.
+
+## Uruchomienie lokalne
+```bash
+pip install -r requirements.txt
+python scripts/make_sample_data.py     # przykładowe .xlsx
+python -m app.ingest.build_index       # (opcjonalnie) prebuild indeksu
+uvicorn app.main:app --port 8002
+```
+
+## Migracja do SQL (gdy nadejdzie czas)
+```bash
+python -m app.ingest.to_sql            # Excel -> tabela 'records' + indeksy
+export DATA_PROVIDER=sql               # przełącz warstwę — reszta systemu bez zmian
+```

services/data/app/bases.py

@@ -0,0 +1,66 @@
+"""Przegląd baz na udziale i ich globalne włączanie/wyłączanie (DAN-15 / PRE-09).
+
+Wymaganie przedefiniowane pod model serwerowy: pliki baz leżą na stałym NFS, więc
+nie wybiera się folderu — potrzeba za to WIDZIEĆ, jakie bazy są dostępne (nazwa +
+metaopis) i móc globalnie zdecydować, które biorą udział w interpretacji.
+
+Stan przełączników trzymamy DEKLARATYWNIE w zmiennej `DISABLED_BASES`, a nie w
+pliku, bo warstwa danych nie ma gdzie trwale zapisywać: udział z bazami jest
+montowany read-only, a katalog cache to `emptyDir` (ginie przy restarcie poda).
+Zapis do pliku po cichu wracałby więc do stanu sprzed restartu — a ciche
+przywrócenie wyłączonej bazy jest gorsze niż konieczność edycji konfiguracji.
+
+Dopasowanie jest tolerancyjne: wpis pasuje po nazwie pliku ALBO po ścieżce
+względnej — żeby dało się wyłączyć zarówno „stara_baza.xlsx", jak i
+„archiwum/stara_baza.xlsx".
+"""
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def disabled_entries() -> list[str]:
+    return [e.strip() for e in os.getenv("DISABLED_BASES", "").split(",") if e.strip()]
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return path.name
+
+
+def is_enabled(path: str | Path, root: str | Path, entries: list[str] | None = None) -> bool:
+    """Czy baza bierze udział w wyszukiwaniu interpretacji."""
+    entries = disabled_entries() if entries is None else entries
+    if not entries:
+        return True
+    p = Path(path)
+    rel = _relative(p, Path(root))
+    return not any(e == p.name or e == rel for e in entries)
+
+
+def list_bases(root: str | Path, paths: list[str]) -> list[dict]:
+    """Bazy dostępne na udziale + metaopis. Celowo TANI opis (dane z systemu
+    plików): przy setkach plików liczenie rekordów oznaczałoby wczytanie każdego."""
+    root = Path(root)
+    entries = disabled_entries()
+    out: list[dict] = []
+    for raw in paths:
+        p = Path(raw)
+        try:
+            st = p.stat()
+            size_mb, modified = round(st.st_size / (1024 * 1024), 2), st.st_mtime
+        except OSError:
+            size_mb, modified = None, None
+        out.append({
+            "name": p.name,
+            "path": _relative(p, root),
+            "size_mb": size_mb,
+            "modified": (datetime.fromtimestamp(modified, tz=timezone.utc).strftime("%Y-%m-%d")
+                         if modified else None),
+            "enabled": is_enabled(p, root, entries),
+        })
+    return out

services/data/app/cache/fingerprint.py

@@ -0,0 +1,22 @@
+"""Odcisk pliku = klucz unieważniania cache.
+
+Wszystkie warstwy cache są kluczowane odciskiem pliku. Gdy plik Excela się zmieni,
+zmienia się odcisk -> automatyczny "cache miss" i przebudowa. Domyślnie używamy
+taniego (mtime + rozmiar); sha256 dostępne, gdy potrzeba pewności co do treści.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+
+
+def fingerprint(path: str, strong: bool = False) -> str:
+    if strong:
+        h = hashlib.sha256()
+        with open(path, "rb") as f:
+            for chunk in iter(lambda: f.read(1024 * 1024), b""):
+                h.update(chunk)
+        return "sha256:" + h.hexdigest()[:16]
+
+    st = os.stat(path)
+    return f"mt:{int(st.st_mtime)}:{st.st_size}"

services/data/app/cache/frame_cache.py

@@ -0,0 +1,40 @@
+"""Cache danych: znormalizowany arkusz zapisany jako Parquet.
+
+POZIOM 2 cache — największy zysk wydajności. Parsowanie .xlsx jest wolne
+(dziesiątki–setki ms na duży plik). Po pierwszym wczytaniu zapisujemy
+znormalizowaną ramkę jako Parquet (kolumnowy, kompresowany), kluczowaną odciskiem
+pliku. Kolejne odczyty ładują Parquet — zwykle 10–100x szybciej niż .xlsx i bez
+ponownego wykrywania nagłówka.
+
+Plik Parquet jest też naturalnym formatem pośrednim przy migracji do SQL.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+
+class FrameCache:
+    def __init__(self, cache_dir: Path) -> None:
+        self.dir = cache_dir / "frames"
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def _path(self, fp: str, sheet: str) -> Path:
+        safe = fp.replace(":", "_") + "__" + str(sheet).replace("/", "_")
+        return self.dir / f"{safe}.parquet"
+
+    def get(self, fp: str, sheet: str) -> pd.DataFrame | None:
+        p = self._path(fp, sheet)
+        if p.exists():
+            return pd.read_parquet(p)
+        return None
+
+    def put(self, fp: str, sheet: str, frame: pd.DataFrame) -> None:
+        # Kolumny z heterogenicznych plików Excela bywają mieszane (int + str +
+        # NaN w jednej kolumnie) — pyarrow tego nie zapisze. Warstwa danych i tak
+        # operuje na tekście (wyszukiwanie po .astype(str)), więc zapisujemy ramkę
+        # jako string (brak wartości -> pusty tekst). Gwarantuje to stabilny zapis
+        # Parquet niezależnie od zawartości pliku źródłowego.
+        safe = frame.astype("string").fillna("")
+        safe.to_parquet(self._path(fp, sheet), index=False)

services/data/app/cache/index.py

@@ -0,0 +1,68 @@
+"""Odwrócony indeks: wartość kanonicznego klucza -> które pliki/arkusze ją mają.
+
+POZIOM 4 (i najważniejszy przy skali) — pozwala NIE skanować setek plików przy
+każdym zapytaniu. Budujemy w SQLite indeks: dla wybranych kluczy (np. name, id,
+symbol) zapisujemy, w którym pliku/arkuszu występuje dana wartość. Wyszukiwanie
+najpierw pyta indeks (jeden szybki SELECT), a otwiera tylko trafione pliki.
+
+Ten SQLite indeks jest jednocześnie POMOSTEM do pełnej migracji SQL — rozbudowa
+go o wszystkie kolumny = de facto baza danych (patrz ingest/to_sql.py).
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+class InvertedIndex:
+    def __init__(self, cache_dir: Path) -> None:
+        self._db = sqlite3.connect(str(cache_dir / "index.db"), check_same_thread=False)
+        self._db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS entries (
+                key   TEXT,         -- kanoniczne pole, np. 'name'
+                value TEXT,         -- znormalizowana (lower) wartość
+                file  TEXT,         -- ścieżka pliku
+                sheet TEXT
+            )
+            """
+        )
+        self._db.execute("CREATE INDEX IF NOT EXISTS ix_kv ON entries(key, value)")
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS files (file TEXT PRIMARY KEY, fingerprint TEXT)"
+        )
+        self._db.commit()
+
+    def file_fingerprint(self, file: str) -> str | None:
+        cur = self._db.execute("SELECT fingerprint FROM files WHERE file=?", (file,))
+        row = cur.fetchone()
+        return row[0] if row else None
+
+    def reindex_file(self, file: str, fingerprint: str, rows: list[tuple[str, str, str]]) -> None:
+        """rows: lista (key, value, sheet) dla jednego pliku."""
+        self._db.execute("DELETE FROM entries WHERE file=?", (file,))
+        self._db.executemany(
+            "INSERT INTO entries(key, value, file, sheet) VALUES (?,?,?,?)",
+            [(k, v.lower(), file, sheet) for (k, v, sheet) in rows],
+        )
+        self._db.execute(
+            "INSERT OR REPLACE INTO files(file, fingerprint) VALUES (?,?)", (file, fingerprint)
+        )
+        self._db.commit()
+
+    def lookup(self, key: str, value: str, exact: bool) -> list[tuple[str, str]]:
+        """Zwraca listę (file, sheet) kandydatów do przeszukania."""
+        if exact:
+            cur = self._db.execute(
+                "SELECT DISTINCT file, sheet FROM entries WHERE key=? AND value=?",
+                (key, value.lower()),
+            )
+        else:
+            cur = self._db.execute(
+                "SELECT DISTINCT file, sheet FROM entries WHERE key=? AND value LIKE ?",
+                (key, f"%{value.lower()}%"),
+            )
+        return [(r[0], r[1]) for r in cur.fetchall()]
+
+    def count_files(self) -> int:
+        return self._db.execute("SELECT COUNT(*) FROM files").fetchone()[0]

services/data/app/cache/query_cache.py

@@ -0,0 +1,39 @@
+"""Cache wyników zapytań: in-memory LRU + TTL.
+
+POZIOM 3 cache. Te same zapytania powtarzają się (popularne wyszukiwania). Tu
+trzymamy gotowy wynik przez krótki TTL. Bez zewnętrznych zależności — w produkcji
+można podmienić na Redis (ten sam interfejs get/put), by współdzielić cache
+między instancjami.
+"""
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from typing import Any
+
+
+class QueryCache:
+    def __init__(self, max_size: int = 512, ttl: int = 300) -> None:
+        self.max_size = max_size
+        self.ttl = ttl
+        self._store: OrderedDict[str, tuple[float, Any]] = OrderedDict()
+
+    def get(self, key: str) -> Any | None:
+        item = self._store.get(key)
+        if item is None:
+            return None
+        ts, value = item
+        if time.time() - ts > self.ttl:
+            del self._store[key]
+            return None
+        self._store.move_to_end(key)
+        return value
+
+    def put(self, key: str, value: Any) -> None:
+        self._store[key] = (time.time(), value)
+        self._store.move_to_end(key)
+        while len(self._store) > self.max_size:
+            self._store.popitem(last=False)
+
+    def clear(self) -> None:
+        self._store.clear()

services/data/app/cache/schema_cache.py

@@ -0,0 +1,45 @@
+"""Cache schematu: wykryty wiersz nagłówka + mapowanie kolumn, per (plik, arkusz).
+
+POZIOM 1 cache. Najdroższe jest samo wykrywanie nagłówka i wnioskowanie układu
+kolumn. Robimy to RAZ na wersję pliku i zapisujemy w SQLite. Kolejne odczyty
+pomijają skanowanie.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+
+class SchemaCache:
+    def __init__(self, cache_dir: Path) -> None:
+        self._db = sqlite3.connect(str(cache_dir / "schema.db"), check_same_thread=False)
+        self._db.execute(
+            """
+            CREATE TABLE IF NOT EXISTS schema_cache (
+                fingerprint TEXT,
+                sheet       TEXT,
+                header_row  INTEGER,
+                mapping     TEXT,
+                PRIMARY KEY (fingerprint, sheet)
+            )
+            """
+        )
+        self._db.commit()
+
+    def get(self, fp: str, sheet: str) -> tuple[int, dict[str, str]] | None:
+        cur = self._db.execute(
+            "SELECT header_row, mapping FROM schema_cache WHERE fingerprint=? AND sheet=?",
+            (fp, sheet),
+        )
+        row = cur.fetchone()
+        if row is None:
+            return None
+        return int(row[0]), json.loads(row[1])
+
+    def put(self, fp: str, sheet: str, header_row: int, mapping: dict[str, str]) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO schema_cache VALUES (?,?,?,?)",
+            (fp, sheet, header_row, json.dumps(mapping, ensure_ascii=False)),
+        )
+        self._db.commit()

services/data/app/canary.py

@@ -0,0 +1,70 @@
+"""Rekordy-pułapki (canary) — wykrywanie wycieku baz (DAN-26).
+
+Zabezpieczenie DETEKCYJNE, nie prewencyjne. Kilka unikalnych, wiarygodnie
+wyglądających rekordów wplecionych w bazy: nie zmieniają interpretacji (są
+ODSIEWANE z wyników, więc nie trafiają ani do użytkownika, ani do promptu LLM —
+wymóg LOG-30), ale jeśli kiedyś pojawią się w cudzej kopii, są dowodem pochodzenia.
+
+Pułapkę rozpoznajemy po MARKERZE: unikalny ciąg, który nie występuje w realnych
+danych (wpleciony np. w pole znaczące). Markery i WARIANT tego wdrożenia biorą się
+z konfiguracji (ENV `CANARY_MARKERS`, `CANARY_VARIANT`) — każda kopia może dostać
+swój zestaw. Który wariant trafił do którego wdrożenia trzyma rejestr po stronie
+ops (osobno, poza kodem — patrz docs/canary-registry.md).
+
+Dwa sygnały:
+  * ODSIEWANIE — pułapka w wynikach znika, zanim opuści warstwę danych (log info);
+  * TRIPWIRE — zapytanie CELUJE wprost w marker (ktoś enumeruje bazę, a nie liczy
+    realny horoskop) → log warning, bo to podejrzane zachowanie.
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+log = logging.getLogger("astrololo.data.canary")
+
+
+def _load_markers() -> list[str]:
+    return [m.strip() for m in os.getenv("CANARY_MARKERS", "").split(",") if m.strip()]
+
+
+MARKERS = _load_markers()
+VARIANT = os.getenv("CANARY_VARIANT", "")
+
+
+def _row_is_canary(row: dict, markers: list[str]) -> bool:
+    """Czy KTÓRAKOLWIEK tekstowa wartość wiersza zawiera marker pułapki."""
+    for v in row.values():
+        if isinstance(v, str):
+            for m in markers:
+                if m in v:
+                    return True
+    return False
+
+
+def screen(
+    rows: list[dict], query_value: str = "",
+    markers: list[str] | None = None, variant: str | None = None,
+) -> tuple[list[dict], dict]:
+    """Zwraca (widoczne_wiersze, raport).
+
+    Odsiewa pułapki z wyników (nie opuszczą warstwy danych). Gdy zapytanie celuje
+    wprost w marker — podnosi TRIPWIRE (możliwa enumeracja bazy). Bez skonfigurowanych
+    markerów: przezroczyste (`active=False`), zero kosztu dla normalnego ruchu.
+    """
+    markers = MARKERS if markers is None else markers
+    variant = VARIANT if variant is None else variant
+    if not markers:
+        return rows, {"active": False, "removed": 0, "tripwire": False}
+
+    visible = [r for r in rows if not _row_is_canary(r, markers)]
+    removed = len(rows) - len(visible)
+    tripwire = any(m in (query_value or "") for m in markers)
+
+    if tripwire:
+        log.warning(
+            "CANARY TRIPWIRE: zapytanie celuje wprost w rekord-pułapkę (wariant %s) "
+            "— możliwa enumeracja bazy", variant or "?")
+    elif removed:
+        log.info("Odsiano %d rekord(ów)-pułapek z wyników (wariant %s)", removed, variant or "?")
+    return visible, {"active": True, "removed": removed, "tripwire": tripwire}

services/data/app/config.py

@@ -0,0 +1,52 @@
+"""Konfiguracja warstwy bazodanowej (z ENV).
+
+Najważniejsza zmienna: DATA_PROVIDER. Zmiana 'excel' -> 'sql' przełącza całą
+warstwę na bazę SQL bez dotykania pozostałych modułów (patrz providers/factory.py).
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent  # .../services/data
+
+
+@dataclass
+class Settings:
+    # 'excel' (dziś) albo 'sql' (po migracji)
+    provider: str = field(default_factory=lambda: os.getenv("DATA_PROVIDER", "excel"))
+
+    # Warstwa Excel
+    excel_dir: Path = field(
+        default_factory=lambda: Path(os.getenv("EXCEL_DIR", str(BASE_DIR / "data_files")))
+    )
+    cache_dir: Path = field(
+        default_factory=lambda: Path(os.getenv("CACHE_DIR", str(BASE_DIR / ".cache")))
+    )
+    header_scan_rows: int = field(default_factory=lambda: int(os.getenv("HEADER_SCAN_ROWS", "15")))
+    # Klucze kanoniczne, które trafiają do odwróconego indeksu (przyspiesza wyszukiwanie).
+    indexed_keys: tuple[str, ...] = field(
+        default_factory=lambda: tuple(
+            k.strip() for k in os.getenv("INDEXED_KEYS", "name,id,symbol").split(",") if k.strip()
+        )
+    )
+
+    # Cache zapytań (in-memory)
+    query_cache_size: int = field(default_factory=lambda: int(os.getenv("QUERY_CACHE_SIZE", "512")))
+    query_cache_ttl: int = field(default_factory=lambda: int(os.getenv("QUERY_CACHE_TTL", "300")))
+
+    # Warstwa SQL (po migracji)
+    # Domyślnie SQLite w cache — do testów i pracy lokalnej, bez stawiania bazy.
+    # Na klastrze SQL_URL wskazuje Postgresa i przychodzi z SEKRETU, bo niesie
+    # hasło (patrz deploy: astrololo/README-postgres.md).
+    sql_url: str = field(
+        default_factory=lambda: os.getenv("SQL_URL", "sqlite:///./.cache/astrololo.db")
+    )
+
+    def __post_init__(self) -> None:
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.excel_dir.mkdir(parents=True, exist_ok=True)
+
+
+settings = Settings()

services/data/app/excel/header_detect.py

@@ -0,0 +1,52 @@
+"""Wykrywanie wiersza nagłówka w arkuszu.
+
+Pliki Excela w tej domenie nie mają nagłówka zawsze w pierwszym wierszu — bywają
+puste wiersze, tytuły, metadane. Ta heurystyka skanuje pierwsze N wierszy i
+wybiera ten, który "wygląda jak nagłówek": dużo niepustych, tekstowych,
+unikalnych komórek, po którym następują wiersze danych o podobnym wypełnieniu.
+
+Wynik (indeks wiersza nagłówka) jest CACHE'OWANY per plik (schema_cache), więc
+ten kosztowny skan robimy raz na wersję pliku.
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def _row_score(raw: pd.DataFrame, i: int) -> float:
+    row = raw.iloc[i]
+    non_null = row.notna()
+    filled = float(non_null.mean()) if len(row) else 0.0
+    if filled == 0:
+        return -1.0
+
+    values = [str(v).strip() for v in row[non_null].tolist()]
+    text_like = sum(1 for v in values if v and not _looks_numeric(v))
+    text_ratio = text_like / max(len(values), 1)
+    uniqueness = len(set(values)) / max(len(values), 1)
+
+    # Wiersze danych pod spodem powinny mieć podobną liczbę wypełnionych kolumn.
+    follow_bonus = 0.0
+    if i + 1 < len(raw):
+        below = raw.iloc[i + 1].notna().mean()
+        follow_bonus = 1.0 - abs(filled - float(below))
+
+    return filled * 0.4 + text_ratio * 0.3 + uniqueness * 0.2 + follow_bonus * 0.1
+
+
+def _looks_numeric(v: str) -> bool:
+    try:
+        float(v.replace(",", "."))
+        return True
+    except ValueError:
+        return False
+
+
+def detect_header_row(raw: pd.DataFrame, max_scan: int = 15) -> int:
+    """Zwraca indeks (0-based) wiersza, który najprawdopodobniej jest nagłówkiem."""
+    best_idx, best_score = 0, float("-inf")
+    for i in range(min(max_scan, len(raw))):
+        score = _row_score(raw, i)
+        if score > best_score:
+            best_idx, best_score = i, score
+    return best_idx

services/data/app/excel/layout.py

@@ -0,0 +1,52 @@
+"""Mapowanie układu kolumn na schemat kanoniczny.
+
+Setki plików mogą mieć te same dane pod różnymi nagłówkami i w różnej kolejności
+kolumn ("Imię", "Name", "NAZWA" -> kanoniczne 'name'). Ta warstwa tłumaczy
+faktyczny układ kolumn pliku na wspólny słownik pól, dzięki czemu reszta systemu
+(i przyszła baza SQL) operuje na jednej, stabilnej nazwie pola.
+
+Aliasowanie jest świadomie wydzielone i konfigurowalne — to jedyne miejsce do
+edycji, gdy pojawi się nowy wariant nagłówka.
+"""
+from __future__ import annotations
+
+import re
+
+# kanoniczne_pole -> zbiór aliasów (po normalizacji)
+CANONICAL_ALIASES: dict[str, set[str]] = {
+    "id": {"id", "identyfikator", "nr", "no", "number"},
+    "name": {"name", "imie", "nazwa", "nazwisko", "title", "tytul"},
+    "symbol": {"symbol", "znak", "sign", "glyph"},
+    "date": {"date", "data", "datetime", "timestamp"},
+    "value": {"value", "wartosc", "val", "amount", "kwota"},
+    "category": {"category", "kategoria", "type", "typ", "group", "grupa"},
+}
+
+
+def _normalize(col: str) -> str:
+    s = str(col).strip().lower()
+    s = re.sub(r"[ąàá]", "a", s)
+    s = s.replace("ł", "l").replace("ż", "z").replace("ź", "z").replace("ć", "c")
+    s = s.replace("ę", "e").replace("ó", "o").replace("ś", "s").replace("ń", "n")
+    s = re.sub(r"[^a-z0-9]+", "", s)
+    return s
+
+
+def build_column_mapping(header_cells: list[str]) -> dict[str, str]:
+    """Zwraca mapę pole_kanoniczne -> faktyczna_nazwa_kolumny dla danego pliku.
+
+    Kolumny nierozpoznane są zachowywane pod swoją (znormalizowaną) nazwą, więc
+    nic nie ginie — po prostu nie mają aliasu kanonicznego.
+    """
+    reverse: dict[str, str] = {}
+    for canonical, aliases in CANONICAL_ALIASES.items():
+        for alias in aliases:
+            reverse[alias] = canonical
+
+    mapping: dict[str, str] = {}
+    for actual in header_cells:
+        norm = _normalize(actual)
+        canonical = reverse.get(norm, norm or "col")
+        # pierwsze trafienie wygrywa (stabilność przy duplikatach)
+        mapping.setdefault(canonical, actual)
+    return mapping

services/data/app/excel/loader.py

@@ -0,0 +1,43 @@
+"""Wczytanie pojedynczego arkusza do znormalizowanej ramki danych.
+
+Łączy wykrywanie nagłówka (header_detect) z mapowaniem układu kolumn (layout).
+Zwraca ramkę o KANONICZNYCH nazwach kolumn — gotową do indeksowania, cache'owania
+(parquet) i ewentualnego załadowania do SQL.
+
+To jest jedyne miejsce, które "rozumie" format Excela. Reszta systemu jej nie
+widzi.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+from app.excel.header_detect import detect_header_row
+from app.excel.layout import build_column_mapping
+
+
+@dataclass
+class LoadedSheet:
+    frame: pd.DataFrame              # dane z kanonicznymi kolumnami
+    header_row: int                  # wykryty indeks nagłówka
+    column_mapping: dict[str, str]   # pole_kanoniczne -> oryginalna_nazwa
+
+
+def load_sheet(path: str, sheet: str | int = 0, header_scan_rows: int = 15) -> LoadedSheet:
+    raw = pd.read_excel(path, sheet_name=sheet, header=None, dtype=object)
+    header_row = detect_header_row(raw, max_scan=header_scan_rows)
+
+    header_cells = [str(c) for c in raw.iloc[header_row].tolist()]
+    mapping = build_column_mapping(header_cells)
+
+    data = raw.iloc[header_row + 1 :].copy()
+    data.columns = header_cells
+    data = data.dropna(how="all")
+
+    # przenazwij na kanoniczne pola: {oryginał -> kanoniczne}
+    inverse = {orig: canon for canon, orig in mapping.items()}
+    data = data.rename(columns=inverse)
+    data = data.reset_index(drop=True)
+
+    return LoadedSheet(frame=data, header_row=header_row, column_mapping=mapping)

services/data/app/files.py

@@ -0,0 +1,379 @@
+"""Rejestr plików baz: stan użycia, wgrywanie, archiwizacja, walidacja (DAN-27).
+
+CO SIĘ ZMIENIA WZGLĘDEM DAN-15. Dotąd włączanie i wyłączanie baz szło przez
+zmienną `DISABLED_BASES` — deklaratywnie, bo warstwa danych nie miała gdzie
+zapisywać stanu (udział read-only, cache jako emptyDir). Teraz stan jest KLIKANY,
+więc musi być trwały: udział jest zapisywalny, a stan leży w pliku obok baz.
+
+STANY PLIKU
+  active      — bierze udział w wyszukiwaniu,
+  ready       — sprawny, ale świadomie odstawiony; można włączyć jednym kliknięciem,
+  archived    — ZAMROŻONY: nie bierze udziału, ma znacznik czasu archiwizacji,
+                sam plik zostaje nietknięty. To jedyna forma „usuwania" dostępna
+                osobie wgrywającej dane,
+  quarantine  — wgrany, ale nie przeszedł walidacji. NIE JEST TRACONY; decyzję,
+                czy go skasować, podejmuje wyłącznie administrator.
+
+DLACZEGO KWARANTANNA JEST NIEWIDOCZNA POZA ADMINISTRATOREM. Zasada z PRE-27 mówi,
+że konto ograniczone nie ma skąd wiedzieć o mechanizmach, których nie obsługuje.
+Gdyby plik w kwarantannie był widoczny z powodem odrzucenia, każdy wgrywający
+poznałby reguły walidacji — a te są narzędziem administratora. Osoba wgrywająca
+widzi więc plik jako „oczekuje na zatwierdzenie", bez powodu i bez reguł.
+
+REGUŁY WALIDACJI są danymi, nie kodem: administrator ustawia je z ekranu. Trzymamy
+je w tym samym pliku stanu, bo stan i reguły zmieniają się razem i muszą przetrwać
+restart tak samo.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+ACTIVE, READY, ARCHIVED, QUARANTINE = "active", "ready", "archived", "quarantine"
+
+# Nazwa puli może przyjść z zewnątrz (login konta w wersji demo), więc przechodzi
+# przez sito: wyłącznie znaki bezpieczne w nazwie katalogu. Bez tego „../..” albo
+# ukośnik wyprowadziłyby zapytanie poza udział — czyli wprost do cudzych baz.
+_TENANT_OK = re.compile(r"[^A-Za-z0-9._-]")
+
+
+def tenant_root(root: Path | str, tenant: str = "") -> Path:
+    """Katalog, w którym mieszka pula danego konta.
+
+    Puste `tenant` = cały udział, czyli zachowanie produkcji. Nazwa jest
+    OCZYSZCZANA, a nie sprawdzana i odrzucana: sito zamienia wszystko podejrzane
+    na podkreślenie, więc żadne wejście nie wyprowadzi ścieżki wyżej."""
+    root = Path(root)
+    name = _TENANT_OK.sub("_", (tenant or "").strip()).strip("._")
+    return root / name if name else root
+USABLE = frozenset({ACTIVE})
+
+# Stany, o których wolno wiedzieć osobie bez uprawnień administracyjnych.
+# Kwarantanna świadomie poza listą — patrz nagłówek modułu.
+VISIBLE_TO_EVERYONE = frozenset({ACTIVE, READY, ARCHIVED})
+
+_lock = threading.Lock()
+
+DEFAULT_RULES: dict = {
+    "extensions": [".xlsx"],
+    "max_size_mb": 50,
+    "min_rows": 1,
+    "required_columns": [],      # puste = bez wymagań co do nagłówków
+    "reject_duplicate_content": True,
+}
+
+
+def state_path(root: Path | str) -> Path:
+    """Plik stanu — obok baz, chyba że wskazano inaczej.
+
+    Sprawdzamy NAPIS ze środowiska, nie Path(napis): Path("") to Path("."),
+    czyli wartość PRAWDZIWA, więc `Path(os.getenv(...)) or domyślna` zawsze
+    wybierało pustą zmienną i zapisywało stan do katalogu bieżącego."""
+    override = os.getenv("FILES_STATE", "").strip()
+    return Path(override) if override else Path(root) / ".files-state.json"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def sha256_of(path: Path | str) -> str:
+    """Skrót treści pliku — tożsamość pliku niezależna od nazwy.
+
+    Przyda się też krokowi drugiemu (lustro w SQL): to po nim poznamy, że plik
+    na dysku rozjechał się z tym, co wczytano do bazy."""
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+# ── stan ─────────────────────────────────────────────────────────────────
+
+def _read_state(root: Path) -> dict:
+    try:
+        with open(state_path(root), encoding="utf-8") as fh:
+            data = json.load(fh)
+    except (FileNotFoundError, json.JSONDecodeError):
+        data = {}
+    files = data.get("files")
+    rules = data.get("rules")
+    return {
+        "files": files if isinstance(files, dict) else {},
+        "rules": {**DEFAULT_RULES, **(rules if isinstance(rules, dict) else {})},
+    }
+
+
+def _write_state(root: Path, data: dict) -> None:
+    path = state_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Atomowo: plik stanu opisuje CAŁY zbiór baz, więc obcięcie go w połowie
+    # zapisu skasowałoby wiedzę o wszystkich naraz.
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False, indent=1, sort_keys=True)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def rules(root: Path | str) -> dict:
+    return _read_state(Path(root))["rules"]
+
+
+def set_rules(root: Path | str, new: dict) -> dict:
+    root = Path(root)
+    with _lock:
+        data = _read_state(root)
+        merged = {**data["rules"]}
+        for key, value in (new or {}).items():
+            if key in DEFAULT_RULES:
+                merged[key] = value
+        data["rules"] = merged
+        _write_state(root, data)
+    return merged
+
+
+# ── walidacja ────────────────────────────────────────────────────────────
+
+def validate(path: Path | str, root: Path | str, *, digest: str = "",
+             known_digests: dict[str, str] | None = None) -> list[str]:
+    """Lista POWODÓW odrzucenia. Pusta lista = plik nadaje się do użytku.
+
+    Zwracamy powody, a nie samo „tak/nie", bo administrator ma zobaczyć, CZEGO
+    plikowi brakuje — inaczej poprawianie bazy byłoby zgadywanką. Poza konto
+    administracyjne ta lista nie wychodzi."""
+    p, rs = Path(path), rules(root)
+    why: list[str] = []
+
+    exts = [str(e).lower() for e in rs.get("extensions") or []]
+    if exts and p.suffix.lower() not in exts:
+        why.append(f"rozszerzenie {p.suffix or '(brak)'} spoza dozwolonych: {', '.join(exts)}")
+
+    try:
+        size_mb = p.stat().st_size / (1024 * 1024)
+    except OSError:
+        return why + ["pliku nie da się odczytać"]
+    cap = float(rs.get("max_size_mb") or 0)
+    if cap and size_mb > cap:
+        why.append(f"rozmiar {size_mb:.1f} MB przekracza limit {cap:g} MB")
+
+    if rs.get("reject_duplicate_content") and known_digests:
+        digest = digest or sha256_of(p)
+        twin = next((name for name, d in known_digests.items()
+                     if d == digest and name != p.name), None)
+        if twin:
+            why.append(f"treść identyczna z plikiem „{twin}”")
+
+    required = [str(c).strip() for c in (rs.get("required_columns") or []) if str(c).strip()]
+    min_rows = int(rs.get("min_rows") or 0)
+    if required or min_rows:
+        why += _inspect_workbook(p, required, min_rows)
+    return why
+
+
+def _inspect_workbook(path: Path, required: list[str], min_rows: int) -> list[str]:
+    """Zagląda do arkusza: nagłówki i liczba wierszy.
+
+    read_only + tylko pierwszy arkusz — plik bazy potrafi mieć kilkadziesiąt MB,
+    a wczytanie go w całości przy każdym wgraniu zatkałoby usługę."""
+    try:
+        import openpyxl
+
+        wb = openpyxl.load_workbook(path, read_only=True, data_only=True)
+    except Exception as e:                       # noqa: BLE001 — każdy błąd = powód
+        return [f"nie udało się otworzyć arkusza ({type(e).__name__})"]
+    why: list[str] = []
+    try:
+        ws = wb[wb.sheetnames[0]]
+        rows = ws.iter_rows(values_only=True)
+        header = [str(c).strip().lower() for c in (next(rows, ()) or ()) if c is not None]
+        missing = [c for c in required if c.strip().lower() not in header]
+        if missing:
+            why.append(f"brak wymaganych kolumn: {', '.join(missing)}")
+        if min_rows:
+            seen = sum(1 for i, _ in enumerate(rows) if i < min_rows)
+            if seen < min_rows:
+                why.append(f"za mało wierszy danych ({seen} < {min_rows})")
+    finally:
+        wb.close()
+    return why
+
+
+# ── rejestr ──────────────────────────────────────────────────────────────
+
+def _scan(root: Path) -> list[Path]:
+    """Pliki na udziale, bez śmieci technicznych.
+
+    Pomijamy nie tylko ukryte PLIKI, ale i wszystko, co leży w ukrytym KATALOGU:
+    filtr po samej nazwie pliku wciągał do rejestru zawartość `.cache`, bo pliki
+    w środku nie zaczynają się od kropki. Efekt: cache podawany jako baza, a przy
+    pierwszym uruchomieniu jeszcze przyjmowany jako aktywny."""
+    def ukryta_sciezka(p: Path) -> bool:
+        return any(part.startswith(".") for part in p.relative_to(root).parts[:-1])
+
+    return [p for p in sorted(root.glob("**/*"))
+            if p.is_file() and not p.name.startswith((".", "~$"))
+            and not ukryta_sciezka(p)]
+
+
+def _adopt_existing(root: Path) -> dict:
+    """Pierwsze uruchomienie: bazy zastane na udziale są OD RAZU w użyciu.
+
+    Bez tego wdrożenie DAN-27 wyłączyłoby wyszukiwanie. Dotąd bazy działały
+    domyślnie (wyłączało się je jawnie przez DISABLED_BASES); po przejściu na
+    rejestr plik bez wpisu dostaje `ready`, czyli NIE w użyciu — więc pusty stan
+    po wdrożeniu oznaczałby, że program nagle niczego nie znajduje. Ta cicha
+    zmiana zachowania byłaby gorsza od awarii, bo wygląda jak pusta baza.
+
+    Rozróżnienie jest celowe: `ready` dotyczy plików WGRANYCH przez ekran (te
+    ktoś musi świadomie włączyć), a nie zastanych przy przejściu na rejestr.
+
+    Zapis stanu może się nie udać (udział read-only) — wtedy trudno, przy każdym
+    uruchomieniu przyjmiemy je na nowo. Zachowanie jest to samo, koszt żaden."""
+    files = {str(p.relative_to(root)): {"status": ACTIVE, "adopted_at": _now()}
+             for p in _scan(root)}
+    data = {"files": files, "rules": {**DEFAULT_RULES}}
+    try:
+        _write_state(root, data)
+    except OSError:
+        pass
+    return data
+
+
+def registry(root: Path | str, *, for_admin: bool = False) -> list[dict]:
+    """Pliki na udziale wraz ze stanem. `for_admin` odsłania kwarantannę i powody.
+
+    Filtrowanie siedzi TUTAJ, a nie w szablonie: gdyby pliki w kwarantannie
+    dochodziły do przeglądarki i były tylko ukrywane stylem, wystarczyłby podgląd
+    źródła strony, żeby poznać reguły walidacji."""
+    root = Path(root)
+    # Brak PLIKU stanu = pierwsze uruchomienie. Pusty słownik przy istniejącym
+    # pliku to co innego: ktoś świadomie wszystko odstawił, więc nie wskrzeszamy.
+    data = _read_state(root) if state_path(root).exists() else _adopt_existing(root)
+    out: list[dict] = []
+    for p in _scan(root):
+        rel = str(p.relative_to(root))
+        row = data["files"].get(rel, {})
+        status = row.get("status") or READY
+        if status == QUARANTINE and not for_admin:
+            continue
+        try:
+            st = p.stat()
+            size_mb = round(st.st_size / (1024 * 1024), 2)
+            modified = datetime.fromtimestamp(st.st_mtime, tz=timezone.utc).strftime("%Y-%m-%d")
+        except OSError:
+            size_mb, modified = None, None
+        entry = {
+            "name": p.name, "path": rel, "size_mb": size_mb, "modified": modified,
+            "status": status, "in_use": status in USABLE,
+            # `enabled` to TA SAMA informacja pod nazwą, której używa reszta
+            # świata: endpoint /bases, warstwa logiczna i ekran „Ustawienia"
+            # (DAN-15/PRE-09). Rejestr wszedł w miejsce starej listy baz, więc
+            # musi mówić jej językiem — inaczej każdy odbiorca dostaje KeyError,
+            # a to była właśnie awaria /bases po wdrożeniu DAN-27.
+            "enabled": status in USABLE,
+            "archived_at": row.get("archived_at") or "",
+            "uploaded_at": row.get("uploaded_at") or "",
+            "uploaded_by": row.get("uploaded_by") or "",
+            "sha256": row.get("sha256") or "",
+        }
+        if for_admin:
+            entry["rejected_for"] = list(row.get("rejected_for") or [])
+        out.append(entry)
+    return out
+
+
+def usable_paths(root: Path | str) -> list[str]:
+    """Ścieżki baz, które FAKTYCZNIE biorą udział w wyszukiwaniu."""
+    root = Path(root)
+    return [str(root / e["path"]) for e in registry(root, for_admin=True) if e["in_use"]]
+
+
+def _touch(root: Path, rel: str, **fields) -> dict:
+    with _lock:
+        data = _read_state(root)
+        row = {**data["files"].get(rel, {}), **fields}
+        data["files"][rel] = row
+        _write_state(root, data)
+    return row
+
+
+def set_status(root: Path | str, rel: str, status: str, *, by: str = "") -> dict:
+    """Zmienia stan pliku. Włączyć do użytku można TYLKO plik, który przeszedł
+    walidację — to jest właśnie ta bramka, o której mowa w wymaganiu."""
+    root = Path(root)
+    target = root / rel
+    if not target.is_file():
+        raise ValueError(f"Nie ma pliku „{rel}”.")
+    if status not in {ACTIVE, READY, ARCHIVED, QUARANTINE}:
+        raise ValueError(f"Nieznany stan: {status}")
+
+    data = _read_state(root)
+    current = (data["files"].get(rel) or {}).get("status") or READY
+    if status == ACTIVE:
+        if current == QUARANTINE:
+            raise ValueError("Plik nie może trafić do użytku.")
+        known = {e["path"]: e["sha256"] for e in registry(root, for_admin=True) if e["sha256"]}
+        why = validate(target, root, known_digests=known)
+        if why:
+            _touch(root, rel, status=QUARANTINE, rejected_for=why, checked_at=_now())
+            raise ValueError("Plik nie może trafić do użytku.")
+
+    fields = {"status": status, "changed_at": _now(), "changed_by": by}
+    if status == ARCHIVED:
+        # Znacznik czasu archiwizacji to wymóg: „zamrożona forma z timestampem".
+        fields["archived_at"] = _now()
+    elif status == ACTIVE:
+        fields["archived_at"] = ""
+        fields["rejected_for"] = []
+    return _touch(root, rel, **fields)
+
+
+def store_upload(root: Path | str, filename: str, content: bytes, *, by: str = "") -> dict:
+    """Zapisuje wgrany plik i od razu go sprawdza.
+
+    Plik zostaje NIEZALEŻNIE od wyniku walidacji — nie tracimy niczego, co ktoś
+    wgrał. Zmienia się tylko to, czy da się go włączyć do użytku."""
+    root = Path(root)
+    safe = re.sub(r"[^A-Za-z0-9._ -]", "_", Path(filename or "").name).strip() or "plik"
+    target = root / safe
+    stem, suffix, n = Path(safe).stem, Path(safe).suffix, 1
+    while target.exists():                       # nie nadpisujemy cudzej bazy
+        target = root / f"{stem}-{n}{suffix}"
+        n += 1
+    root.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(content)
+
+    rel = str(target.relative_to(root))
+    digest = sha256_of(target)
+    known = {e["path"]: e["sha256"] for e in registry(root, for_admin=True)
+             if e["sha256"] and e["path"] != rel}
+    why = validate(target, root, digest=digest, known_digests=known)
+    _touch(root, rel, status=QUARANTINE if why else READY, rejected_for=why,
+           sha256=digest, uploaded_at=_now(), uploaded_by=by, checked_at=_now())
+    return {"path": rel, "name": target.name, "accepted": not why}
+
+
+def delete(root: Path | str, rel: str) -> None:
+    """Nieodwracalne skasowanie pliku — wyłącznie dla administratora."""
+    root = Path(root)
+    target = root / rel
+    if not target.is_file():
+        raise ValueError(f"Nie ma pliku „{rel}”.")
+    target.unlink()
+    with _lock:
+        data = _read_state(root)
+        data["files"].pop(rel, None)
+        _write_state(root, data)

services/data/app/ingest/build_index.py

@@ -0,0 +1,25 @@
+"""Wstępne zbudowanie cache + odwróconego indeksu dla wszystkich plików Excela.
+
+Uruchom raz po wgraniu/aktualizacji plików (albo zostaw warmup przy starcie usługi):
+
+    python -m app.ingest.build_index
+"""
+from __future__ import annotations
+
+from app.config import settings
+from app.providers.excel_provider import ExcelDataProvider
+
+
+def main() -> None:
+    provider = ExcelDataProvider(settings)
+    files = provider._excel_files()
+    print(f"Indeksuję {len(files)} plików z {settings.excel_dir} ...")
+    for i, path in enumerate(files, 1):
+        provider._ensure_indexed(path)
+        if i % 25 == 0 or i == len(files):
+            print(f"  {i}/{len(files)}")
+    print(f"Gotowe. Zaindeksowane pliki: {provider.index.count_files()}")
+
+
+if __name__ == "__main__":
+    main()

services/data/app/ingest/to_sql.py

@@ -0,0 +1,53 @@
+"""ETL migracji: setki plików Excela -> jedna zoptymalizowana tabela SQL.
+
+To jest "łatwa droga na przyszłość". Skrypt używa DOKŁADNIE tego samego loadera
+co warstwa Excela (wykrywanie nagłówka + mapowanie kolumn kanonicznych), więc
+dane trafiają do SQL już znormalizowane i spójne. Po załadowaniu wystarczy
+ustawić DATA_PROVIDER=sql.
+
+    python -m app.ingest.to_sql
+
+Kroki:
+  1. wczytaj każdy plik loaderem -> ramka o kanonicznych kolumnach,
+  2. dołóż kolumnę źródła (_source_file) dla audytu,
+  3. dopisz do tabeli 'records',
+  4. załóż indeksy na kluczach kanonicznych (przyspieszenie zapytań).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+from sqlalchemy import create_engine, text
+
+from app.config import settings
+from app.excel.loader import load_sheet
+
+
+def main() -> None:
+    engine = create_engine(settings.sql_url, future=True)
+    files = sorted(Path(settings.excel_dir).glob("**/*.xlsx"))
+    print(f"Migruję {len(files)} plików -> {settings.sql_url}")
+
+    first = True
+    for path in files:
+        if path.name.startswith("~$"):
+            continue
+        loaded = load_sheet(str(path), header_scan_rows=settings.header_scan_rows)
+        frame = loaded.frame.copy()
+        frame["_source_file"] = path.name
+        frame.to_sql("records", engine, if_exists="replace" if first else "append", index=False)
+        first = False
+
+    with engine.connect() as conn:
+        for key in settings.indexed_keys:
+            try:
+                conn.execute(text(f"CREATE INDEX IF NOT EXISTS ix_records_{key} ON records({key})"))
+            except Exception as e:  # kolumna może nie istnieć w tym zbiorze
+                print(f"  (pomijam indeks {key}: {e})")
+        conn.commit()
+    print("Migracja zakończona. Ustaw DATA_PROVIDER=sql aby przełączyć warstwę.")
+
+
+if __name__ == "__main__":
+    main()

services/data/app/link_crypto.py

@@ -0,0 +1,525 @@
+"""Szyfrowanie łączy między warstwami (PRE-16 / LOG-33).
+
+Do tej pory warstwy rozmawiały ze sobą zwykłym HTTP-em wewnątrz klastra. Token
+międzywarstwowy (LOG-32) mówił KTO pyta, ale nie ukrywał CZEGO dotyczy odpowiedź
+— a płyną nią surowe wiersze oryginalnych baz interpretacyjnych, czyli rdzeń
+produktu. Kto podsłuchał ruch wewnątrz sieci (drugi pod, port mirror na switchu,
+zrzut z węzła), miał je w całości.
+
+Ten moduł zamyka tę drogę: **AES-256-GCM** na ciele każdego żądania i odpowiedzi.
+GCM daje jednocześnie poufność i uwierzytelnienie — cudzy albo podmieniony bajt
+nie odszyfruje się w ogóle, więc nie ma osobnego problemu „zaszyfrowane, ale
+podatne na modyfikację".
+
+**Dwa niezależne klucze**, po jednym na parę rozmówców:
+  * ``LINK_KEY_PRESENTATION_LOGIC`` — prezentacja ↔ logika,
+  * ``LINK_KEY_LOGIC_DATA``        — logika ↔ dane.
+Dzięki temu przejęcie klucza prezentacji nie daje dostępu do warstwy danych,
+gdzie leżą całe bazy. Logika trzyma oba, bo rozmawia w obie strony.
+
+Z każdego klucza łącza wyprowadzamy **osobne podklucze na kierunek** (HKDF).
+Żądanie i odpowiedź nigdy nie szyfrują się tym samym kluczem, więc powtórzenie
+losowej jednorazówki w jedną stronę nie osłabia drugiej.
+
+Format ramki (bo strumień odpowiedzi może iść kawałkami — patrz okno postępu):
+
+    [4 bajty długości][magia "AL1"][12 bajtów jednorazówki][szyfrogram + znacznik]
+
+Do materiału uwierzytelnianego (AAD) wchodzą kierunek, ścieżka, znacznik czasu
+i numer ramki. Skutek: ramki nie da się przekleić do innego endpointu, odtworzyć
+po czasie (dopuszczalny poślizg ``MAX_SKEW``) ani przestawić w strumieniu.
+
+Bez ustawionego klucza moduł **przepuszcza ruch otwartym tekstem** (dev, zgodność
+wstecz) i krzyczy o tym przy starcie. Gdy klucz JEST ustawiony, warstwa serwerowa
+działa fail-closed: nieszyfrowane żądanie dostaje odmowę, żeby przypadkowa
+regresja po stronie klienta nie oznaczała cichego powrotu do jawnego ruchu.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import logging
+import os
+import struct
+import time
+from typing import Iterable, Iterator
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+log = logging.getLogger("astrololo.link")
+
+MAGIC = b"AL1"
+VERSION = "v1"
+NONCE_BYTES = 12
+KEY_BYTES = 32                      # AES-256
+LENGTH_PREFIX = 4
+MAX_FRAME = 64 * 1024 * 1024        # zapora przed alokacją z podanej długości
+MAX_SKEW_SECONDS = 300.0
+
+HEADER_ENC = "X-Astrololo-Enc"
+HEADER_TS = "X-Astrololo-Enc-Ts"
+CONTENT_TYPE = "application/vnd.astrololo.enc"
+
+ENV_PRESENTATION_LOGIC = "LINK_KEY_PRESENTATION_LOGIC"
+ENV_LOGIC_DATA = "LINK_KEY_LOGIC_DATA"
+# Trzecia para: prezentacja ↔ render (PRE-24). Osobny klucz, jak przy pozostałych —
+# usługa render dostaje CAŁY raport (dane urodzeniowe + opisy z baz), więc przejęcie
+# jej klucza nie może otwierać łącza do logiki ani do danych.
+ENV_PRESENTATION_RENDER = "LINK_KEY_PRESENTATION_RENDER"
+ENV_REQUIRED = "LINK_ENCRYPTION_REQUIRED"
+
+REQUEST, RESPONSE = b"req", b"res"
+
+# Sondy k8s pukają tu bez klucza i tak ma zostać — inaczej pierwsza literówka
+# w sekrecie kładłaby pody zamiast pokazać błąd w aplikacji.
+PUBLIC_PATHS = frozenset({"/health"})
+
+
+class LinkError(Exception):
+    """Cokolwiek poszło nie tak z kopertą — celowo bez szczegółów na zewnątrz."""
+
+
+# --------------------------------------------------------------------- klucze
+
+def parse_key(raw: str) -> bytes:
+    """Klucz z konfiguracji: hex (64 znaki) albo base64. Zawsze 32 bajty."""
+    text = raw.strip()
+    if not text:
+        raise LinkError("pusty klucz łącza")
+    try:
+        key = bytes.fromhex(text)
+    except ValueError:
+        try:
+            key = base64.b64decode(text, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise LinkError("klucz łącza nie jest ani hexem, ani base64") from exc
+    if len(key) != KEY_BYTES:
+        raise LinkError(
+            f"klucz łącza ma {len(key)} B zamiast {KEY_BYTES} — wygeneruj przez "
+            f"`openssl rand -hex 32`"
+        )
+    return key
+
+
+def key_from_env(env_name: str) -> bytes | None:
+    """Klucz albo None. Zły klucz to wyjątek OD RAZU — nie przy pierwszym żądaniu."""
+    raw = os.getenv(env_name, "")
+    return parse_key(raw) if raw.strip() else None
+
+
+def encryption_required() -> bool:
+    """Czy brak klucza ma być błędem, a nie cichym powrotem do jawnego ruchu.
+
+    Serwer sam z siebie broni się fail-closed, ale to za mało: klient BEZ klucza
+    wysyła pytanie otwartym tekstem i dopiero potem dostaje odmowę — czyli treść
+    zapytania zdążyła już przelecieć przez sieć. Ta flaga zatrzymuje go, zanim
+    cokolwiek opuści proces. Ustawiana razem z kluczami we wdrożeniu.
+    """
+    return os.getenv(ENV_REQUIRED, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _subkey(link_key: bytes, direction: bytes) -> bytes:
+    return HKDF(
+        algorithm=hashes.SHA256(), length=KEY_BYTES, salt=None,
+        info=b"astrololo/link/" + direction,
+    ).derive(link_key)
+
+
+class Link:
+    """Jedna para rozmówców: klucz plus wyprowadzone z niego podklucze."""
+
+    def __init__(self, link_key: bytes) -> None:
+        self._by_direction = {
+            REQUEST: AESGCM(_subkey(link_key, REQUEST)),
+            RESPONSE: AESGCM(_subkey(link_key, RESPONSE)),
+        }
+
+    # ---------------------------------------------------------- pojedyncza ramka
+
+    def _aad(self, direction: bytes, path: str, stamp: str, seq: int) -> bytes:
+        return b"|".join([MAGIC, direction, path.encode("utf-8"),
+                          stamp.encode("ascii"), str(seq).encode("ascii")])
+
+    def seal(self, direction: bytes, path: str, stamp: str, seq: int,
+             plaintext: bytes) -> bytes:
+        nonce = os.urandom(NONCE_BYTES)
+        sealed = self._by_direction[direction].encrypt(
+            nonce, plaintext, self._aad(direction, path, stamp, seq))
+        return MAGIC + nonce + sealed
+
+    def open(self, direction: bytes, path: str, stamp: str, seq: int,
+             frame: bytes) -> bytes:
+        if not frame.startswith(MAGIC):
+            raise LinkError("ramka bez znacznika protokołu")
+        body = frame[len(MAGIC):]
+        if len(body) <= NONCE_BYTES:
+            raise LinkError("ramka za krótka")
+        nonce, sealed = body[:NONCE_BYTES], body[NONCE_BYTES:]
+        try:
+            return self._by_direction[direction].decrypt(
+                nonce, sealed, self._aad(direction, path, stamp, seq))
+        except InvalidTag as exc:
+            # Jeden komunikat na wszystkie przypadki: zły klucz, podmieniony bajt,
+            # przeklejenie z innej ścieżki, przestawiona ramka. Rozróżnianie ich
+            # na zewnątrz podpowiadałoby atakującemu, w co trafił.
+            raise LinkError("nie udało się odszyfrować — zły klucz albo naruszone dane") from exc
+
+    # ------------------------------------------------------------ strumień ramek
+
+    def seal_stream(self, direction: bytes, path: str, stamp: str,
+                    chunks: Iterable[bytes]) -> Iterator[bytes]:
+        for seq, chunk in enumerate(chunks):
+            yield frame_out(self.seal(direction, path, stamp, seq, chunk))
+
+    def open_stream(self, direction: bytes, path: str, stamp: str,
+                    raw: bytes) -> Iterator[bytes]:
+        for seq, frame in enumerate(frames_in(raw)):
+            yield self.open(direction, path, stamp, seq, frame)
+
+    def open_all(self, direction: bytes, path: str, stamp: str, raw: bytes) -> bytes:
+        return b"".join(self.open_stream(direction, path, stamp, raw))
+
+
+# ---------------------------------------------------------------- ramkowanie
+
+def frame_out(payload: bytes) -> bytes:
+    return struct.pack(">I", len(payload)) + payload
+
+
+def frames_in(raw: bytes) -> Iterator[bytes]:
+    """Rozbiera bufor na ramki. Ucięty strumień to błąd, nie cicha strata danych."""
+    offset = 0
+    while offset < len(raw):
+        if offset + LENGTH_PREFIX > len(raw):
+            raise LinkError("urwana ramka (brak nagłówka długości)")
+        (size,) = struct.unpack(">I", raw[offset:offset + LENGTH_PREFIX])
+        if size > MAX_FRAME:
+            raise LinkError("ramka ponad dopuszczalny rozmiar")
+        offset += LENGTH_PREFIX
+        if offset + size > len(raw):
+            raise LinkError("urwana ramka (za mało danych)")
+        yield raw[offset:offset + size]
+        offset += size
+
+
+def unframe_incremental(buffer: bytearray) -> Iterator[bytes]:
+    """Wyjmuje z bufora KOMPLETNE ramki i zjada je; resztę zostawia na później.
+
+    Dla odbioru na żywo: kawałki przychodzą podzielone dowolnie i ramka potrafi
+    rozjechać się między dwa odczyty.
+    """
+    while True:
+        if len(buffer) < LENGTH_PREFIX:
+            return
+        (size,) = struct.unpack(">I", buffer[:LENGTH_PREFIX])
+        if size > MAX_FRAME:
+            raise LinkError("ramka ponad dopuszczalny rozmiar")
+        if len(buffer) < LENGTH_PREFIX + size:
+            return
+        frame = bytes(buffer[LENGTH_PREFIX:LENGTH_PREFIX + size])
+        del buffer[:LENGTH_PREFIX + size]
+        yield frame
+
+
+# ------------------------------------------------------------- świeżość ruchu
+
+def stamp_now() -> str:
+    return f"{time.time():.3f}"
+
+
+def check_stamp(stamp: str) -> None:
+    """Odrzuca ramki spoza okna czasowego — inaczej podsłuchane żądanie dałoby się
+    odtworzyć w dowolnym momencie w przyszłości."""
+    try:
+        sent = float(stamp)
+    except (TypeError, ValueError) as exc:
+        raise LinkError("brak albo błędny znacznik czasu") from exc
+    if abs(time.time() - sent) > MAX_SKEW_SECONDS:
+        raise LinkError("znacznik czasu poza dopuszczalnym oknem")
+
+
+# =========================================================== strona serwerowa
+
+class LinkCryptoMiddleware:
+    """Rozszyfrowuje wchodzące żądania i zaszyfrowuje wychodzące odpowiedzi.
+
+    Napisane jako czyste ASGI, nie ``@app.middleware("http")``, bo trzeba
+    podmienić CIAŁO żądania jeszcze zanim zobaczy je FastAPI, oraz przepuścić
+    odpowiedź strumieniową kawałek po kawałku, bez zbierania jej w pamięci.
+    """
+
+    def __init__(self, app, link: Link | None, layer: str) -> None:
+        self.app = app
+        self.link = link
+        self.layer = layer
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http" or self.link is None or scope["path"] in PUBLIC_PATHS:
+            return await self.app(scope, receive, send)
+
+        path = scope["path"]
+        headers = {k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope["headers"]}
+
+        if headers.get(HEADER_ENC.lower()) != VERSION:
+            # Fail-closed. Klucz jest ustawiony, więc jawne żądanie oznacza albo
+            # pomyłkę w konfiguracji, albo kogoś obcego — w obu wypadkach nie
+            # chcemy po cichu wrócić do jawnego ruchu.
+            log.warning("warstwa %s: odrzucone żądanie bez szyfrowania łącza (%s)",
+                        self.layer, path)
+            return await _refuse(send, "Łącze międzywarstwowe wymaga szyfrowania.")
+
+        stamp = headers.get(HEADER_TS.lower(), "")
+        try:
+            check_stamp(stamp)
+            plaintext = self.link.open_all(REQUEST, path, stamp, await _read_body(receive))
+        except LinkError as exc:
+            log.warning("warstwa %s: %s (%s)", self.layer, exc, path)
+            return await _refuse(send, "Nie udało się odczytać zaszyfrowanego żądania.")
+
+        scope = dict(scope)
+        scope["headers"] = _rewritten_headers(scope["headers"], len(plaintext))
+        await self.app(scope, _replay(plaintext, receive), self._sealing_send(send, path))
+
+    def _sealing_send(self, send, path: str):
+        state: dict = {"stamp": "", "seq": 0}
+
+        async def sealing(message):
+            if message["type"] == "http.response.start":
+                state["stamp"] = stamp_now()
+                keep = [(k, v) for k, v in message.get("headers", [])
+                        if k.lower() not in (b"content-length", b"content-type")]
+                message = dict(message)
+                message["headers"] = keep + [
+                    (b"content-type", CONTENT_TYPE.encode()),
+                    (HEADER_ENC.lower().encode(), VERSION.encode()),
+                    (HEADER_TS.lower().encode(), state["stamp"].encode()),
+                ]
+                return await send(message)
+
+            if message["type"] == "http.response.body":
+                chunk = message.get("body", b"")
+                sealed = b""
+                if chunk:
+                    sealed = frame_out(self.link.seal(
+                        RESPONSE, path, state["stamp"], state["seq"], chunk))
+                    state["seq"] += 1
+                return await send({"type": "http.response.body", "body": sealed,
+                                   "more_body": message.get("more_body", False)})
+
+            return await send(message)
+
+        return sealing
+
+
+def _rewritten_headers(raw: Iterable[tuple[bytes, bytes]], length: int):
+    """Po odszyfrowaniu ciało ma inną długość i zwykły typ — inaczej FastAPI
+    próbowałby sparsować JSON o cudzej deklarowanej wielkości."""
+    kept = [(k, v) for k, v in raw if k.lower() not in (b"content-length", b"content-type")]
+    kept.append((b"content-length", str(length).encode()))
+    if length:
+        kept.append((b"content-type", b"application/json"))
+    return kept
+
+
+async def _read_body(receive) -> bytes:
+    body = bytearray()
+    while True:
+        message = await receive()
+        if message["type"] == "http.disconnect":
+            raise LinkError("rozłączenie w trakcie odbioru żądania")
+        body += message.get("body", b"")
+        if not message.get("more_body", False):
+            return bytes(body)
+
+
+def _replay(body: bytes, original):
+    """Podstawia odszyfrowane ciało jako jedyną porcję wejścia dla aplikacji.
+
+    Po oddaniu ciała oddajemy głos ORYGINALNEMU `receive`, zamiast od razu
+    zgłaszać rozłączenie. Odpowiedź strumieniowa nasłuchuje bowiem rozłączenia
+    równolegle do wysyłania i przerywa się, gdy je zobaczy — na skróconej wersji
+    okno postępu dostawało pustą odpowiedź, choć zwykłe żądania działały.
+    """
+    delivered = False
+
+    async def receive():
+        nonlocal delivered
+        if delivered:
+            return await original()
+        delivered = True
+        return {"type": "http.request", "body": body, "more_body": False}
+
+    return receive
+
+
+async def _refuse(send, detail: str) -> None:
+    """Odmowa leci JAWNIE — rozmówca właśnie pokazał, że nie umie odszyfrować,
+    więc zaszyfrowany komunikat o błędzie byłby dla niego nieczytelny."""
+    payload = f'{{"detail":"{detail}"}}'.encode("utf-8")
+    await send({"type": "http.response.start", "status": 400, "headers": [
+        (b"content-type", b"application/json"),
+        (b"content-length", str(len(payload)).encode()),
+    ]})
+    await send({"type": "http.response.body", "body": payload})
+
+
+def install(app, env_name: str, layer: str):
+    """Podpina szyfrowanie łącza. Wołać PO `security.install`, żeby także odmowa
+    tokenowa (401) wracała zaszyfrowana — inaczej klient by jej nie odczytał."""
+    link_key = key_from_env(env_name)
+    if link_key is None and encryption_required():
+        # Celowo wywracamy start. Ta sama zasada co przy sekrecie logowania:
+        # wolimy widoczną awarię niż usługę, która wstała i po cichu nie chroni
+        # niczego. Pod w CrashLoop widać od razu, jawny ruch — nie.
+        raise LinkError(
+            f"{ENV_REQUIRED} jest włączone, ale {env_name} nie ustawiony — "
+            f"warstwa {layer} nie wystartuje bez klucza łącza"
+        )
+    if link_key is None:
+        log.warning(
+            "UWAGA: %s nie ustawiony — warstwa %s rozmawia z sąsiadem JAWNYM tekstem, "
+            "więc treść baz interpretacyjnych jest widoczna dla każdego, kto podsłucha "
+            "ruch wewnątrz sieci.", env_name, layer,
+        )
+        return None
+    link = Link(link_key)
+    app.add_middleware(LinkCryptoMiddleware, link=link, layer=layer)
+    log.info("warstwa %s: łącze szyfrowane (AES-256-GCM, klucz z %s)", layer, env_name)
+    return link
+
+
+# ============================================================ strona kliencka
+
+def call(client, method: str, url: str, *, payload=None,
+         headers: dict[str, str] | None = None, link: Link | None) -> bytes:
+    """Żądanie do sąsiedniej warstwy; zwraca odszyfrowane ciało odpowiedzi.
+
+    Ścieżkę do materiału uwierzytelnianego bierzemy Z URL-a, a nie z osobnego
+    argumentu — gdyby klient i serwer liczyły ją inaczej, każde żądanie kończyłoby
+    się niejasnym błędem odszyfrowania.
+    """
+    import json as _json
+
+    import httpx
+
+    request_headers = dict(headers or {})
+    if link is None:
+        if encryption_required():
+            # Zatrzymujemy się PRZED wysłaniem. Gdyby polecieć jawnie i dopiero
+            # zebrać odmowę, pytanie byłoby już na kablu — a to właśnie ono niesie
+            # sygnifikatory, o które pytamy bazę.
+            raise LinkError(
+                f"{ENV_REQUIRED} jest włączone, ale brak klucza łącza — żądanie "
+                f"NIE zostało wysłane, żeby jego treść nie poszła jawnym tekstem"
+            )
+        response = client.request(method, url, json=payload, headers=request_headers)
+        response.raise_for_status()
+        return response.content
+
+    path = httpx.URL(url).path
+    stamp = stamp_now()
+    plaintext = b"" if payload is None else _json.dumps(payload).encode("utf-8")
+    body = frame_out(link.seal(REQUEST, path, stamp, 0, plaintext))
+    request_headers.update({HEADER_ENC: VERSION, HEADER_TS: stamp,
+                            "Content-Type": CONTENT_TYPE})
+
+    response = client.request(method, url, content=body, headers=request_headers)
+    if response.status_code >= 400 and response.headers.get(HEADER_ENC) != VERSION:
+        log.error("łącze %s odmówiło: %s", path, response.text[:200])
+    response.raise_for_status()
+    if response.headers.get(HEADER_ENC) != VERSION:
+        raise LinkError("odpowiedź przyszła nieszyfrowana, choć klucz łącza jest ustawiony")
+    reply_stamp = response.headers.get(HEADER_TS, "")
+    check_stamp(reply_stamp)
+    return link.open_all(RESPONSE, path, reply_stamp, response.content)
+
+
+def call_json(client, method: str, url: str, *, payload=None,
+              headers: dict[str, str] | None = None, link: Link | None):
+    import json as _json
+
+    return _json.loads(call(client, method, url, payload=payload,
+                            headers=headers, link=link))
+
+
+def open_response_stream(response, link: Link | None) -> Iterator[bytes]:
+    """Odbiór odpowiedzi płynącej kawałkami (okno postępu).
+
+    Ramka potrafi rozjechać się między dwa odczyty z gniazda, więc składamy ją
+    w buforze zamiast zakładać, że każdy kawałek to komplet.
+    """
+    if link is None:
+        yield from response.iter_bytes()
+        return
+    if response.headers.get(HEADER_ENC) != VERSION:
+        raise LinkError("strumień przyszedł nieszyfrowany, choć klucz łącza jest ustawiony")
+    stamp = response.headers.get(HEADER_TS, "")
+    check_stamp(stamp)
+    path = response.request.url.path
+    buffer = bytearray()
+    seq = 0
+    for chunk in response.iter_bytes():
+        buffer += chunk
+        for frame in unframe_incremental(buffer):
+            yield link.open(RESPONSE, path, stamp, seq, frame)
+            seq += 1
+    if buffer:
+        raise LinkError("strumień urwał się w połowie ramki")
+
+
+def stream_lines(client, url: str, *, payload, headers: dict[str, str] | None = None,
+                 link: Link | None) -> Iterator[str]:
+    """Strumieniowe POST zwracające kolejne NIEPUSTE linie NDJSON — na żywo.
+
+    Dla okna postępu: linie muszą docierać w trakcie pracy, nie na końcu, więc
+    czytamy strumień, a nie całe ciało. Gdy łącze ma klucz, żądanie jest
+    pieczętowane, a odpowiedź odszyfrowywana ramka po ramce; granice ramek NIE
+    pokrywają się z granicami linii, więc sklejamy bajty w buforze i tniemy je
+    dopiero na znakach nowej linii.
+
+    Bez klucza zachowuje się jak dotąd (surowy strumień), żeby dev bez sekretów
+    działał bez zmian.
+    """
+    import json as _json
+
+    import httpx as _httpx
+
+    request_headers = dict(headers or {})
+    if link is None:
+        if encryption_required():
+            # Ten sam kontrakt co w `call`: nie wypuszczamy jawnego żądania, gdy
+            # szyfrowanie jest wymagane. Bez tego serwer owszem odrzuca (400), ale
+            # ciało żądania — tu dane urodzenia — zdążyłoby już pójść w eter.
+            raise LinkError(
+                f"{ENV_REQUIRED} jest włączone, ale brak klucza łącza — strumień "
+                f"NIE został wysłany, żeby jego treść nie poszła jawnym tekstem"
+            )
+        with client.stream("POST", url, json=payload, headers=request_headers) as response:
+            response.raise_for_status()
+            for text_line in response.iter_lines():
+                if text_line:
+                    yield text_line
+        return
+
+    path = _httpx.URL(url).path
+    stamp = stamp_now()
+    body = frame_out(link.seal(REQUEST, path, stamp, 0, _json.dumps(payload).encode("utf-8")))
+    request_headers.update({HEADER_ENC: VERSION, HEADER_TS: stamp, "Content-Type": CONTENT_TYPE})
+    with client.stream("POST", url, content=body, headers=request_headers) as response:
+        response.raise_for_status()
+        buffer = bytearray()
+        for plain in open_response_stream(response, link):
+            buffer += plain
+            while True:
+                nl = buffer.find(b"\n")
+                if nl < 0:
+                    break
+                text_line = bytes(buffer[:nl])
+                del buffer[:nl + 1]
+                if text_line:
+                    yield text_line.decode("utf-8")
+        if buffer:
+            yield bytes(buffer).decode("utf-8")

services/data/app/main.py

@@ -0,0 +1,147 @@
+"""Warstwa BAZODANOWA — usługa HTTP.
+
+Jedyne zadanie: przyjąć znormalizowane zapytanie z warstwy logicznej, wyszukać
+dane (w Excelu z cache lub w SQL) i zwrócić je w górę. Nie zna warstwy logicznej
+ani prezentacji.
+"""
+# build-marker: 2026-07-25 wymuszenie nowego obrazu po incydencie z tagiem :latest
+from __future__ import annotations
+
+import base64
+import binascii
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException
+
+from app import canary, files, link_crypto, security
+from app.config import settings
+from app.models import HealthInfo, SearchQuery, SearchResult
+from pydantic import BaseModel
+from app.providers.factory import build_provider
+
+provider = build_provider(settings)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    provider.warmup()  # zbuduj/odśwież indeks i cache przy starcie
+    yield
+
+
+# Bez /docs, /redoc i /openapi.json: te trasy oddają KOMPLETNY katalog funkcji —
+# nazwy tras, kształty żądań, listę dostawców modeli — i to każdemu, kto potrafi
+# je otworzyć, bez żadnego logowania. Ochrona zakładek w prezentacji nic nie
+# daje, gdy obok stoi usługa, która sama się spisuje (PRE-27).
+app = FastAPI(title="astrololo · warstwa bazodanowa", lifespan=lifespan,
+              docs_url=None, redoc_url=None, openapi_url=None)
+security.install(app, "danych")       # token międzywarstwowy (LOG-32)
+# Szyfrowanie łącza od logiki. PO `security.install`, żeby także odmowa
+# tokenowa wracała zaszyfrowana — inaczej klient nie umiałby jej odczytać.
+link_crypto.install(app, link_crypto.ENV_LOGIC_DATA, "danych")
+
+
+@app.post("/search", response_model=SearchResult)
+def search(query: SearchQuery) -> SearchResult:
+    result = provider.search(query)
+    # Rekordy-pułapki (DAN-26) odsiewamy TU, na wyjściu z warstwy danych — dzięki
+    # temu nie dotrą ani wyżej, ani do promptu LLM (LOG-30), niezależnie od dostawcy.
+    visible, report = canary.screen(result.rows, query.value)
+    if report["active"]:
+        result.rows = visible
+        result.total = len(visible)
+    return result
+
+
+@app.get("/bases")
+def bases() -> dict:
+    """Bazy dostępne na udziale + metaopis i stan włączenia (DAN-15/PRE-09).
+
+    Same METADANE — nazwy plików, rozmiar, data. Żadnej treści baz, więc podgląd
+    listy nie jest kolejną drogą do ich wyniesienia."""
+    items = provider.list_bases()
+    return {"bases": items, "enabled": sum(1 for b in items if b["enabled"]), "total": len(items)}
+
+
+# ── zarządzanie plikami baz (DAN-27) ─────────────────────────────────────
+# Warstwa danych jest właścicielem plików, więc to ona nimi zarządza. Uprawnienia
+# rozstrzyga PREZENTACJA (PRE-27) i przekazuje tu wynik jako `for_admin` / `by` —
+# ta warstwa nie zna kont i nie ma jak ich znać. Nie jest to dziura: warstwa
+# danych stoi za tokenem międzywarstwowym i szyfrowanym łączem, więc rozmawia
+# z nią wyłącznie warstwa logiczna.
+
+class FilesQuery(BaseModel):
+    for_admin: bool = False
+    # Pula konta (PRE-29). Puste = cały udział — tak woła produkcja, która o pulach
+    # nic nie wie. Wersja demo podaje login, przez co widzi wyłącznie swój katalog.
+    tenant: str = ""
+
+
+class FileAction(BaseModel):
+    path: str
+    status: str = ""
+    by: str = ""
+    tenant: str = ""
+
+
+class FileUpload(BaseModel):
+    filename: str
+    content_b64: str
+    by: str = ""
+    tenant: str = ""
+
+
+class RulesUpdate(BaseModel):
+    rules: dict
+    tenant: str = ""
+
+
+@app.post("/files")
+def files_list(q: FilesQuery) -> dict:
+    """Rejestr plików. Kwarantanna WYCHODZI stąd tylko przy for_admin — filtrujemy
+    u źródła, żeby nie dało się jej odczytać z podglądu źródła strony."""
+    root = files.tenant_root(settings.excel_dir, q.tenant)
+    return {"files": files.registry(root, for_admin=q.for_admin),
+            "rules": files.rules(root) if q.for_admin else {},
+            "root": str(root)}
+
+
+@app.post("/files/status")
+def files_status(a: FileAction) -> dict:
+    try:
+        row = files.set_status(files.tenant_root(settings.excel_dir, a.tenant),
+                               a.path, a.status, by=a.by)
+    except ValueError as e:
+        raise HTTPException(422, str(e)) from e
+    return {"path": a.path, "status": row.get("status")}
+
+
+@app.post("/files/upload")
+def files_upload(u: FileUpload) -> dict:
+    """Plik wędruje w base64 wewnątrz zaszyfrowanego łącza — tym samym kanałem,
+    co reszta ruchu międzywarstwowego. Osobny, nieszyfrowany kanał na pliki
+    byłby obejściem PRE-16."""
+    try:
+        raw = base64.b64decode(u.content_b64, validate=True)
+    except (binascii.Error, ValueError) as e:
+        raise HTTPException(422, "Nieczytelna zawartość pliku.") from e
+    return files.store_upload(files.tenant_root(settings.excel_dir, u.tenant),
+                              u.filename, raw, by=u.by)
+
+
+@app.post("/files/delete")
+def files_delete(a: FileAction) -> dict:
+    try:
+        files.delete(files.tenant_root(settings.excel_dir, a.tenant), a.path)
+    except ValueError as e:
+        raise HTTPException(422, str(e)) from e
+    return {"deleted": a.path}
+
+
+@app.post("/files/rules")
+def files_rules(u: RulesUpdate) -> dict:
+    return {"rules": files.set_rules(files.tenant_root(settings.excel_dir, u.tenant), u.rules)}
+
+
+@app.get("/health", response_model=HealthInfo)
+def health() -> HealthInfo:
+    return provider.health()

services/data/app/models.py

@@ -0,0 +1,49 @@
+"""Kontrakt danych warstwy bazodanowej.
+
+Te modele są JEDYNYM publicznym interfejsem tej warstwy. Warstwa logiczna zna
+wyłącznie te kształty (poprzez HTTP/JSON) — nie wie nic o Excelu, cache ani SQL.
+Dzięki temu można podmienić implementację (Excel -> SQL) bez zmiany pozostałych
+warstw.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SearchQuery(BaseModel):
+    """Znormalizowane zapytanie wyszukiwania przychodzące z warstwy logicznej."""
+
+    key: str = Field(..., description="Pole/kolumna kanoniczna, po której szukamy, np. 'name'.")
+    value: str = Field(..., description="Szukana wartość.")
+    exact: bool = Field(False, description="Dopasowanie dokładne vs. zawieranie (contains).")
+    # Górny limit celowo niski: to zapytanie oddaje SUROWE wiersze baz, więc wysoki
+    # pułap zamienia je w narzędzie do masowego pobrania (LOG-32). 5000 = tyle, ile
+    # realnie potrzebuje build_report na jeden obiekt.
+    limit: int = Field(50, ge=1, le=5000)
+    fields: list[str] | None = Field(
+        None, description="Lista pól kanonicznych do zwrócenia; None = wszystkie."
+    )
+    # PULA KONTA (PRE-29). Puste = cały udział, czyli zachowanie produkcji, która
+    # o pulach nic nie wie. Ustawione = wyszukiwanie widzi WYŁĄCZNIE podkatalog
+    # tego konta. Używa tego wersja demo, gdzie każde konto ma własny, niewidoczny
+    # dla pozostałych zbiór baz.
+    tenant: str = Field("", description="Pula plików konta; puste = cały udział.")
+
+
+class SearchResult(BaseModel):
+    """Wynik wyszukiwania zwracany w górę do warstwy logicznej."""
+
+    rows: list[dict[str, Any]]
+    total: int
+    elapsed_ms: float
+    cache: str = Field("miss", description="hit/miss/partial — skąd pochodzą dane.")
+    provider: str = Field(..., description="Nazwa aktywnej implementacji, np. 'excel' lub 'sql'.")
+
+
+class HealthInfo(BaseModel):
+    status: str = "ok"
+    provider: str
+    indexed_files: int = 0
+    details: dict[str, Any] = Field(default_factory=dict)

services/data/app/providers/base.py

@@ -0,0 +1,34 @@
+"""Abstrakcyjny interfejs dostawcy danych (wzorzec Repository/Strategy).
+
+To jest klucz do "łatwej migracji do SQL". Warstwa bazodanowa udostępnia na
+zewnątrz tylko ten kontrakt. Dziś realizuje go ExcelDataProvider, jutro
+SqlDataProvider — bez żadnej zmiany w warstwie logicznej i prezentacji.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app.models import HealthInfo, SearchQuery, SearchResult
+
+
+class DataProvider(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    def search(self, query: SearchQuery) -> SearchResult:
+        """Wyszuka dane i zwróci je w górę. JEDYNE zadanie tej warstwy."""
+
+    @abstractmethod
+    def health(self) -> HealthInfo:
+        ...
+
+    def warmup(self) -> None:
+        """Opcjonalne wstępne zbudowanie cache/indeksu przy starcie."""
+        return None
+
+    def list_bases(self) -> list[dict]:
+        """Bazy widoczne dla dostawcy + metaopis i stan włączenia (DAN-15/PRE-09).
+
+        Opcjonalne: dostawca SQL nie operuje na plikach, więc domyślnie pusto —
+        UI pokaże wtedy, że nie ma czego przełączać, zamiast się wywrócić."""
+        return []

services/data/app/providers/excel_provider.py

@@ -0,0 +1,189 @@
+"""ExcelDataProvider — wyszukiwanie w setkach plików .xlsx z 4-poziomowym cache.
+
+Ścieżka zapytania (od najszybszej):
+  1) QueryCache (in-memory)  -> gotowy wynik
+  2) InvertedIndex (SQLite)  -> które pliki w ogóle otwierać (zamiast skanu setek)
+  3) FrameCache (Parquet)    -> wczytanie pliku bez parsowania .xlsx
+  4) SchemaCache (SQLite)    -> bez ponownego wykrywania nagłówka/układu kolumn
+  ...dopiero gdy wszystko spudłuje, czytamy .xlsx i wypełniamy cache.
+
+Cała ta złożoność jest UKRYTA za interfejsem DataProvider.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import pandas as pd
+
+from app.cache.fingerprint import fingerprint
+from app.cache.frame_cache import FrameCache
+from app.cache.index import InvertedIndex
+from app.cache.query_cache import QueryCache
+from app.cache.schema_cache import SchemaCache
+from app.config import Settings
+from app.excel.header_detect import detect_header_row
+from app.excel.layout import build_column_mapping
+from app.models import HealthInfo, SearchQuery, SearchResult
+from app.providers.base import DataProvider
+
+
+class ExcelDataProvider(DataProvider):
+    name = "excel"
+
+    def __init__(self, settings: Settings) -> None:
+        self.s = settings
+        self.schema = SchemaCache(settings.cache_dir)
+        self.frames = FrameCache(settings.cache_dir)
+        self.index = InvertedIndex(settings.cache_dir)
+        self.queries = QueryCache(settings.query_cache_size, settings.query_cache_ttl)
+
+    # ---- ładowanie pojedynczego arkusza z pełnym cache ----
+    def _load_frame(self, path: str, sheet: str | int = 0) -> pd.DataFrame:
+        fp = fingerprint(path)
+        sheet_key = str(sheet)
+
+        cached = self.frames.get(fp, sheet_key)        # poziom 2: Parquet
+        if cached is not None:
+            return cached
+
+        raw = pd.read_excel(path, sheet_name=sheet, header=None, dtype=object)
+        meta = self.schema.get(fp, sheet_key)          # poziom 1: schemat
+        if meta is None:
+            header_row = detect_header_row(raw, self.s.header_scan_rows)
+            header_cells = [str(c) for c in raw.iloc[header_row].tolist()]
+            mapping = build_column_mapping(header_cells)
+            self.schema.put(fp, sheet_key, header_row, mapping)
+        else:
+            header_row, mapping = meta
+            header_cells = [str(c) for c in raw.iloc[header_row].tolist()]
+
+        data = raw.iloc[header_row + 1 :].copy()
+        data.columns = header_cells
+        data = data.dropna(how="all")
+        inverse = {orig: canon for canon, orig in mapping.items()}
+        data = data.rename(columns=inverse).reset_index(drop=True)
+
+        self.frames.put(fp, sheet_key, data)           # zapisz Parquet na przyszłość
+        return data
+
+    # ---- budowa odwróconego indeksu (warmup / po zmianie pliku) ----
+    def _ensure_indexed(self, path: str) -> None:
+        fp = fingerprint(path)
+        if self.index.file_fingerprint(path) == fp:
+            return  # aktualny
+        frame = self._load_frame(path)
+        rows: list[tuple[str, str, str]] = []
+        for key in self.s.indexed_keys:
+            if key in frame.columns:
+                for v in frame[key].dropna().astype(str).unique():
+                    rows.append((key, v, "0"))
+        self.index.reindex_file(path, fp, rows)
+
+    def warmup(self) -> None:
+        for path in self._excel_files():
+            try:
+                self._ensure_indexed(path)
+            except Exception as e:  # jeden uszkodzony plik nie może zablokować startu
+                print(f"[data] pominięto plik przy indeksowaniu: {path} — {e}")
+
+    def _excel_files(self) -> list[str]:
+        base = Path(self.s.excel_dir)
+        return [str(p) for p in sorted(base.glob("**/*.xlsx")) if not p.name.startswith("~$")]
+
+    def _enabled_files(self, paths: list[str], tenant: str = "") -> list[str]:
+        """Bazy biorące udział w wyszukiwaniu.
+
+        Źródłem prawdy jest REJESTR PLIKÓW (DAN-27) — stan klikany z ekranu,
+        trwały na udziale. Zmienna DISABLED_BASES z DAN-15 zostaje jako awaryjne
+        wyłączenie z konfiguracji: gdy jest ustawiona, odsiewa DODATKOWO. Nie
+        odwrotnie — inaczej ktoś z dostępem do ekranu mógłby włączyć bazę
+        wyłączoną świadomie na poziomie wdrożenia.
+        """
+        # `bases` MUSI być zaimportowane tutaj — modułowego importu nie ma,
+        # a przepisując tę funkcję pod rejestr usunąłem lokalny. Efekt: NameError
+        # przy KAŻDYM wyszukiwaniu, czyli 500 z warstwy danych.
+        from app import bases, files
+
+        usable = set(files.usable_paths(files.tenant_root(self.s.excel_dir, tenant)))
+        out = [p for p in paths if p in usable]
+        entries = bases.disabled_entries()
+        if entries:
+            out = [p for p in out if bases.is_enabled(p, self.s.excel_dir, entries)]
+        return out
+
+    def list_bases(self) -> list[dict]:
+        """Bazy dostępne na udziale + metaopis + stan włączenia (DAN-15/PRE-09)."""
+        from app import bases
+
+        from app import files
+
+        return files.registry(self.s.excel_dir, for_admin=True)
+
+    # ---- publiczne API ----
+    def search(self, query: SearchQuery) -> SearchResult:
+        t0 = time.perf_counter()
+        # Lista wyłączonych baz wchodzi do klucza cache: bez tego zmiana ustawień
+        # oddawałaby wynik sprzed zmiany, czyli treść bazy uznanej za wyłączoną.
+        from app import bases
+
+        disabled = ",".join(bases.disabled_entries())
+        # PULA MUSI BYĆ W KLUCZU. Bez niej wynik policzony dla jednego konta
+        # trafiłby z cache do drugiego — czyli cicha wymiana treści baz między
+        # kontami, niewidoczna w logach i nie do wykrycia z zewnątrz.
+        cache_key = (f"{query.key}|{query.value}|{query.exact}|{query.limit}"
+                     f"|{query.fields}|{disabled}|{query.tenant}")
+
+        hit = self.queries.get(cache_key)              # poziom 3: wynik zapytania
+        if hit is not None:
+            hit = hit.model_copy(update={"cache": "hit", "elapsed_ms": _ms(t0)})
+            return hit
+
+        candidates = self.index.lookup(query.key, query.value, query.exact)
+        if not candidates:
+            # brak w indeksie (np. klucz nieindeksowany) -> przeszukaj wszystkie pliki
+            candidates = [(p, "0") for p in self._excel_files()]
+        # bazy wyłączone globalnie (DAN-15) pomijamy niezależnie od źródła kandydatów
+        allowed = set(self._enabled_files([p for p, _ in candidates], query.tenant))
+        candidates = [(p, s) for p, s in candidates if p in allowed]
+
+        rows: list[dict] = []
+        for path, _sheet in candidates:
+            frame = self._load_frame(path)
+            if query.key not in frame.columns:
+                continue
+            col = frame[query.key].astype(str)
+            if query.exact:
+                mask = col.str.lower() == query.value.lower()
+            else:
+                # regex=False: wartości sygnifikatorów zawierają znaki [ + itd.,
+                # które są metaznakami regex — szukamy dosłownie.
+                mask = col.str.lower().str.contains(query.value.lower(), na=False, regex=False)
+            matched = frame[mask]
+            if query.fields:
+                keep = [c for c in query.fields if c in matched.columns]
+                matched = matched[keep]
+            rows.extend(matched.to_dict(orient="records"))
+            if len(rows) >= query.limit:
+                break
+
+        result = SearchResult(
+            rows=rows[: query.limit],
+            total=len(rows),
+            elapsed_ms=_ms(t0),
+            cache="miss",
+            provider=self.name,
+        )
+        self.queries.put(cache_key, result)
+        return result
+
+    def health(self) -> HealthInfo:
+        return HealthInfo(
+            provider=self.name,
+            indexed_files=self.index.count_files(),
+            details={"excel_dir": str(self.s.excel_dir), "files_on_disk": len(self._excel_files())},
+        )
+
+
+def _ms(t0: float) -> float:
+    return round((time.perf_counter() - t0) * 1000, 2)

services/data/app/providers/factory.py

@@ -0,0 +1,19 @@
+"""Fabryka dostawcy danych — jedyne miejsce, które wie o konkretnych implementacjach.
+
+Przełączenie Excel <-> SQL: ustaw DATA_PROVIDER w środowisku. Nic poza tym.
+"""
+from __future__ import annotations
+
+from app.config import Settings
+from app.providers.base import DataProvider
+
+
+def build_provider(settings: Settings) -> DataProvider:
+    if settings.provider == "sql":
+        from app.providers.sql_provider import SqlDataProvider
+
+        return SqlDataProvider(settings)
+
+    from app.providers.excel_provider import ExcelDataProvider
+
+    return ExcelDataProvider(settings)

services/data/app/providers/sql_provider.py

@@ -0,0 +1,47 @@
+"""SqlDataProvider — implementacja docelowa (po migracji z Excela).
+
+Szkielet. Realizuje TEN SAM interfejs DataProvider, więc przełączenie to tylko
+zmiana zmiennej środowiskowej DATA_PROVIDER=sql (patrz factory.py). Warstwa
+logiczna i prezentacji nie zmieniają ani jednej linii.
+
+Dane ładuje do bazy skrypt ingest/to_sql.py (ten sam loader Excela -> tabele SQL).
+"""
+from __future__ import annotations
+
+import time
+
+from sqlalchemy import create_engine, text
+
+from app.config import Settings
+from app.models import HealthInfo, SearchQuery, SearchResult
+from app.providers.base import DataProvider
+
+
+class SqlDataProvider(DataProvider):
+    name = "sql"
+
+    def __init__(self, settings: Settings) -> None:
+        self.s = settings
+        self.engine = create_engine(settings.sql_url, future=True)
+
+    def search(self, query: SearchQuery) -> SearchResult:
+        t0 = time.perf_counter()
+        op = "=" if query.exact else "LIKE"
+        val = query.value if query.exact else f"%{query.value}%"
+        cols = ", ".join(query.fields) if query.fields else "*"
+        # UWAGA: nazwy kolumn/tabel walidować względem białej listy schematu.
+        sql = text(f"SELECT {cols} FROM records WHERE {query.key} {op} :v LIMIT :lim")
+        with self.engine.connect() as conn:
+            rows = [dict(r._mapping) for r in conn.execute(sql, {"v": val, "lim": query.limit})]
+        return SearchResult(
+            rows=rows,
+            total=len(rows),
+            elapsed_ms=round((time.perf_counter() - t0) * 1000, 2),
+            cache="miss",
+            provider=self.name,
+        )
+
+    def health(self) -> HealthInfo:
+        with self.engine.connect() as conn:
+            n = conn.execute(text("SELECT COUNT(*) FROM records")).scalar() or 0
+        return HealthInfo(provider=self.name, indexed_files=0, details={"records": int(n)})

services/data/app/security.py

@@ -0,0 +1,50 @@
+"""Uwierzytelnianie międzywarstwowe (LOG-32).
+
+Warstwa danych oddaje SUROWE wiersze baz — to najbardziej wrażliwy punkt całego
+systemu. Bez tego kontrolera wystarczyłoby uderzyć w nią bezpośrednio, z pominięciem
+i logiki, i logowania w UI. Gdy ustawiono INTERNAL_TOKEN, każde żądanie (poza /health)
+musi go przynieść w nagłówku X-Astrololo-Token.
+
+Bez INTERNAL_TOKEN kontrola jest wyłączona (dev / zgodność wstecz) — wtedy przy
+starcie leci ostrzeżenie.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+log = logging.getLogger("astrololo.security")
+
+HEADER = "X-Astrololo-Token"
+PUBLIC_PATHS = frozenset({"/health"})
+
+
+def token() -> str:
+    """Czytany leniwie — konfiguracja może się zmienić bez importu modułu."""
+    return os.getenv("INTERNAL_TOKEN", "")
+
+
+def enabled() -> bool:
+    return bool(token())
+
+
+def install(app, layer: str) -> None:
+    if not enabled():
+        log.warning(
+            "UWAGA: INTERNAL_TOKEN nie ustawiony — warstwa %s przyjmuje żądania od "
+            "kogokolwiek, kto ma do niej dostęp sieciowy.", layer,
+        )
+
+    @app.middleware("http")
+    async def _guard(request: Request, call_next):
+        if request.url.path in PUBLIC_PATHS or not enabled():
+            return await call_next(request)
+        got = request.headers.get(HEADER, "")
+        if not secrets.compare_digest(got, token()):
+            return JSONResponse({"detail": "Brak lub błędny token międzywarstwowy."},
+                                status_code=401)
+        return await call_next(request)

services/data/requirements-dev.txt

@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8.0

services/data/requirements.txt

@@ -0,0 +1,16 @@
+# Dolne ograniczenia (>=) — działa zarówno na Pythonie 3.12 (obraz Docker),
+# jak i na najnowszym 3.14 lokalnie. Przypnij dokładne wersje, gdy ustabilizujesz środowisko.
+fastapi>=0.115
+uvicorn[standard]>=0.34
+pandas>=2.2
+openpyxl>=3.1
+pyarrow>=18.0
+SQLAlchemy>=2.0
+# Sterownik Postgresa (DAN-28). Sam SQLAlchemy nie rozmawia z bazą — bez tego
+# `postgresql+psycopg://…` wywala się dopiero przy PIERWSZYM połączeniu, już na
+# klastrze, komunikatem o braku modułu. [binary] = gotowe koło, bez kompilacji
+# libpq w obrazie.
+psycopg[binary]>=3.2
+pydantic>=2.10
+# Szyfrowanie łącza między warstwami (PRE-16): AES-256-GCM + HKDF
+cryptography>=44.0

services/data/scripts/make_sample_data.py

@@ -0,0 +1,43 @@
+"""Generuje kilka przykładowych plików .xlsx do dema.
+
+Celowo różnicuje: pozycję nagłówka (puste wiersze/tytuł nad nagłówkiem) oraz
+kolejność i nazwy kolumn ("Imię"/"Name", "Symbol"/"Znak") — żeby pokazać działanie
+wykrywania nagłówka i mapowania układu kolumn.
+
+    python scripts/make_sample_data.py
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+OUT = Path(__file__).resolve().parent.parent / "data_files"
+OUT.mkdir(parents=True, exist_ok=True)
+
+SIGNS = ["Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo"]
+
+
+def file_a() -> None:
+    # nagłówek w 1. wierszu, nazwy PL
+    df = pd.DataFrame(
+        {"id": [1, 2, 3], "Imię": SIGNS[:3], "Symbol": ["♈", "♉", "♊"], "Wartość": [10, 20, 30]}
+    )
+    df.to_excel(OUT / "zodiac_pl.xlsx", index=False)
+
+
+def file_b() -> None:
+    # tytuł + pusty wiersz nad nagłówkiem, nazwy EN, inna kolejność kolumn
+    with pd.ExcelWriter(OUT / "zodiac_en.xlsx") as xl:
+        meta = pd.DataFrame([["Tabela astrologiczna — wersja 2"], [None]])
+        meta.to_excel(xl, index=False, header=False, startrow=0)
+        df = pd.DataFrame(
+            {"Sign": ["♋", "♌", "♍"], "Name": SIGNS[3:], "No": [4, 5, 6], "Value": [40, 50, 60]}
+        )
+        df.to_excel(xl, index=False, startrow=2)
+
+
+if __name__ == "__main__":
+    file_a()
+    file_b()
+    print(f"Zapisano przykładowe pliki w {OUT}")

services/data/tests/test_bases.py

@@ -0,0 +1,50 @@
+"""Przegląd baz na udziale i ich globalne wyłączanie (DAN-15 / PRE-09)."""
+import pytest
+
+from app import bases
+
+
+@pytest.fixture(autouse=True)
+def _clean_env(monkeypatch):
+    monkeypatch.delenv("DISABLED_BASES", raising=False)
+
+
+ROOT = "/dane"
+PATHS = [f"{ROOT}/main_base.xlsx", f"{ROOT}/archiwum/stara.xlsx"]
+
+
+def test_everything_enabled_by_default():
+    for b in bases.list_bases(ROOT, PATHS):
+        assert b["enabled"] is True
+
+
+def test_disable_by_file_name(monkeypatch):
+    monkeypatch.setenv("DISABLED_BASES", "stara.xlsx")
+    state = {b["name"]: b["enabled"] for b in bases.list_bases(ROOT, PATHS)}
+    assert state == {"main_base.xlsx": True, "stara.xlsx": False}
+
+
+def test_disable_by_relative_path(monkeypatch):
+    """Wpis może wskazywać ścieżkę względną, nie tylko samą nazwę."""
+    monkeypatch.setenv("DISABLED_BASES", "archiwum/stara.xlsx")
+    assert bases.is_enabled(f"{ROOT}/archiwum/stara.xlsx", ROOT) is False
+    assert bases.is_enabled(f"{ROOT}/main_base.xlsx", ROOT) is True
+
+
+def test_entries_are_trimmed_and_multiple(monkeypatch):
+    monkeypatch.setenv("DISABLED_BASES", " stara.xlsx , main_base.xlsx ")
+    assert [b["enabled"] for b in bases.list_bases(ROOT, PATHS)] == [False, False]
+
+
+def test_listing_carries_metadata_not_content(tmp_path):
+    """Metaopis: nazwa, ścieżka, rozmiar, data — ŻADNEJ treści bazy."""
+    f = tmp_path / "baza.xlsx"
+    f.write_bytes(b"x" * 2048)
+    item = bases.list_bases(tmp_path, [str(f)])[0]
+    assert set(item) == {"name", "path", "size_mb", "modified", "enabled"}
+    assert item["name"] == "baza.xlsx" and item["size_mb"] is not None and item["modified"]
+
+
+def test_missing_file_does_not_crash_the_listing():
+    item = bases.list_bases(ROOT, [f"{ROOT}/nie-ma.xlsx"])[0]
+    assert item["size_mb"] is None and item["modified"] is None

services/data/tests/test_canary.py

@@ -0,0 +1,61 @@
+"""Rekordy-pułapki (canary) — DAN-26.
+
+Testujemy sam MECHANIZM na syntetycznych pułapkach: prawdziwe markery i injekcja
+do baz przychodzą od właściciela produktu. Regresja byłaby CICHA i podwójnie zła:
+albo pułapka wycieka do interpretacji/LLM (zdradza się i psuje wynik), albo
+przestaje odsiewać i nie wiadomo o tym.
+"""
+import pathlib
+
+from app import canary
+
+MAIN = (pathlib.Path(__file__).resolve().parents[1] / "app" / "main.py").read_text(encoding="utf-8")
+
+MARK = "ASTROLOLO-CANARY-7f3a9"          # unikalny — nie wystąpi w realnych danych
+ROWS = [
+    {"significator": "Ma Ari", "effect": "odważny, impulsywny"},
+    {"significator": "Ve Tau " + MARK, "effect": "pułapka — nie dotknie interpretacji"},
+    {"significator": "Su Leo", "effect": "dumny, twórczy"},
+]
+
+
+def test_no_markers_is_transparent():
+    """Bez skonfigurowanych markerów — zero ingerencji, zero kosztu."""
+    out, rep = canary.screen(ROWS, "cokolwiek", markers=[])
+    assert out == ROWS and rep["active"] is False
+
+
+def test_canary_row_is_fenced_from_results():
+    """Pułapka znika z wyników — nie opuści warstwy danych (a więc i promptu LLM)."""
+    out, rep = canary.screen(ROWS, "Ve Tau", markers=[MARK])
+    assert rep["active"] and rep["removed"] == 1
+    assert all(MARK not in str(r) for r in out)          # nigdzie nie ma markera
+    assert len(out) == 2 and {"significator": "Su Leo", "effect": "dumny, twórczy"} in out
+
+
+def test_real_results_pass_through_untouched():
+    out, _ = canary.screen(ROWS, "Ari", markers=[MARK])
+    assert {"significator": "Ma Ari", "effect": "odważny, impulsywny"} in out
+
+
+def test_tripwire_when_query_targets_a_marker():
+    """Zapytanie CELUJĄCE w marker = ktoś enumeruje bazę, nie liczy horoskopu."""
+    _, rep = canary.screen(ROWS, "Ve Tau " + MARK, markers=[MARK])
+    assert rep["tripwire"] is True
+
+
+def test_normal_query_does_not_trip():
+    _, rep = canary.screen(ROWS, "Ma Ari", markers=[MARK])
+    assert rep["tripwire"] is False
+
+
+def test_marker_matched_in_any_string_field():
+    rows = [{"significator": "X", "effect": "opis " + MARK, "extra": 5}]
+    out, rep = canary.screen(rows, "X", markers=[MARK])
+    assert out == [] and rep["removed"] == 1              # marker w polu 'effect' też łapiemy
+
+
+def test_endpoint_fences_before_returning():
+    """/search odsiewa pułapki na wyjściu z warstwy danych (niezależnie od dostawcy)."""
+    assert "canary.screen(result.rows, query.value)" in MAIN
+    assert "result.rows = visible" in MAIN

services/data/tests/test_files.py

@@ -0,0 +1,214 @@
+"""Rejestr plików baz: stany, walidacja, archiwizacja (DAN-27).
+
+Testujemy tu RDZEŃ — bez HTTP i bez uprawnień, bo uprawnienia rozstrzyga
+prezentacja (patrz services/presentation/tests/test_pliki.py). Tutaj chodzi
+o to, żeby żadna operacja nie gubiła pliku i żeby bramka „do użytku tylko po
+walidacji" faktycznie trzymała.
+"""
+import pathlib
+
+import pytest
+
+from app import files
+
+
+@pytest.fixture()
+def root(tmp_path, monkeypatch):
+    monkeypatch.delenv("FILES_STATE", raising=False)
+    return tmp_path
+
+
+def _xlsx(path, rows=3, header=("id", "opis")):
+    import openpyxl
+
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.append(list(header))
+    for i in range(rows):
+        ws.append([i, f"treść {i}"])
+    wb.save(path)
+    return path
+
+
+# ── rejestr i stany ──────────────────────────────────────────────────────
+
+def test_a_file_dropped_on_the_share_is_adopted_as_active(root):
+    """Baza położona na udziale poza aplikacją (np. przez NFS) ma działać —
+    tak było przed DAN-27 i tak ma zostać. Plik WGRANY EKRANEM to inna sprawa:
+    ten wymaga świadomego włączenia (patrz test niżej)."""
+    _xlsx(root / "baza.xlsx")
+    entry = files.registry(root)[0]
+    assert entry["status"] == files.ACTIVE
+    assert entry["in_use"] is True
+
+
+def test_only_active_files_reach_the_search(root):
+    _xlsx(root / "a.xlsx")
+    _xlsx(root / "b.xlsx")
+    files.registry(root)                                   # przyjęcie zastanych
+    files.set_status(root, "b.xlsx", files.READY)           # świadome odstawienie
+    assert [pathlib.Path(p).name for p in files.usable_paths(root)] == ["a.xlsx"]
+    files.set_status(root, "b.xlsx", files.ACTIVE)
+    assert len(files.usable_paths(root)) == 2
+
+
+def test_state_survives_a_restart(root):
+    """Stan jest KLIKANY, więc musi być trwały — inaczej restart poda po cichu
+    przywracałby bazy wyłączone świadomie."""
+    _xlsx(root / "a.xlsx")
+    files.set_status(root, "a.xlsx", files.ACTIVE)
+    assert files.state_path(root).exists()
+    assert files.registry(root)[0]["in_use"] is True
+
+
+# ── archiwizacja ─────────────────────────────────────────────────────────
+
+def test_archiving_freezes_the_file_but_never_removes_it(root):
+    """To jest najdalej idąca operacja osoby wgrywającej dane: plik ZOSTAJE."""
+    p = _xlsx(root / "stara.xlsx")
+    files.set_status(root, "stara.xlsx", files.ACTIVE)
+    files.set_status(root, "stara.xlsx", files.ARCHIVED, by="dane")
+    entry = files.registry(root)[0]
+    assert p.exists(), "plik zniknął z dysku — archiwizacja ma go zachować"
+    assert entry["status"] == files.ARCHIVED
+    assert entry["in_use"] is False
+    assert entry["archived_at"], "brak znacznika czasu archiwizacji"
+
+
+def test_archived_file_cannot_slip_back_into_use_by_itself(root):
+    _xlsx(root / "stara.xlsx")
+    files.set_status(root, "stara.xlsx", files.ARCHIVED)
+    assert files.usable_paths(root) == []
+
+
+# ── walidacja: bramka do użytku ──────────────────────────────────────────
+
+def test_upload_keeps_a_file_that_fails_validation(root):
+    """Rzecz najważniejsza: wgranego pliku NIE TRACIMY, choćby nie przeszedł."""
+    files.set_rules(root, {"extensions": [".xlsx"]})
+    out = files.store_upload(root, "notatka.txt", "to nie jest baza".encode("utf-8"), by="dane")
+    assert out["accepted"] is False
+    assert (root / out["path"]).exists(), "plik odrzucony zniknął z dysku"
+    admin_view = files.registry(root, for_admin=True)[0]
+    assert admin_view["status"] == files.QUARANTINE
+    assert admin_view["rejected_for"], "administrator ma widzieć powód"
+
+
+def test_a_held_file_is_invisible_without_admin_rights(root):
+    """Gdyby plik wstrzymany był widoczny z powodem odrzucenia, każdy wgrywający
+    poznałby reguły walidacji — a te są narzędziem administratora."""
+    files.store_upload(root, "notatka.txt", "nie baza".encode("utf-8"))
+    assert files.registry(root, for_admin=False) == []
+    assert len(files.registry(root, for_admin=True)) == 1
+
+
+def test_a_held_file_cannot_be_switched_into_use(root):
+    files.store_upload(root, "notatka.txt", "nie baza".encode("utf-8"))
+    rel = files.registry(root, for_admin=True)[0]["path"]
+    with pytest.raises(ValueError):
+        files.set_status(root, rel, files.ACTIVE)
+
+
+def test_activation_revalidates_and_holds_a_file_that_stopped_qualifying(root):
+    """Reguły mogą się zmienić PO wgraniu — bramka sprawdza w chwili włączania,
+    a nie tylko przy wgrywaniu."""
+    _xlsx(root / "mala.xlsx", rows=2)
+    files.set_status(root, "mala.xlsx", files.ACTIVE)
+    files.set_rules(root, {"min_rows": 500})
+    files.set_status(root, "mala.xlsx", files.READY)
+    with pytest.raises(ValueError):
+        files.set_status(root, "mala.xlsx", files.ACTIVE)
+    assert (root / "mala.xlsx").exists()
+
+
+@pytest.mark.parametrize("rule,value,bad", [
+    ("extensions", [".xlsx"], "plik.csv"),
+    ("max_size_mb", 0.000001, "plik.xlsx"),
+])
+def test_rules_reject_what_they_are_meant_to(root, rule, value, bad):
+    files.set_rules(root, {rule: value})
+    out = files.store_upload(root, bad, b"x" * 2048)
+    assert out["accepted"] is False
+
+
+def test_required_columns_are_checked_inside_the_workbook(root):
+    files.set_rules(root, {"required_columns": ["id", "znaczenie"]})
+    _xlsx(root / "tmp.xlsx", header=("id", "opis"))
+    why = files.validate(root / "tmp.xlsx", root)
+    assert why and "znaczenie" in why[0]
+
+
+def test_duplicate_content_is_rejected_by_hash_not_by_name(root):
+    files.set_rules(root, {"reject_duplicate_content": True})
+    data = _xlsx(root / "wzor.xlsx").read_bytes()
+    first = files.store_upload(root, "pierwsza.xlsx", data)
+    assert first["accepted"] is True
+    second = files.store_upload(root, "inna-nazwa.xlsx", data)
+    assert second["accepted"] is False
+
+
+def test_upload_never_overwrites_someone_elses_base(root):
+    files.store_upload(root, "baza.xlsx", _xlsx(root / "w.xlsx").read_bytes())
+    (root / "w.xlsx").unlink()
+    files.set_rules(root, {"reject_duplicate_content": False})
+    out = files.store_upload(root, "baza.xlsx", "inna treść".encode("utf-8"))
+    assert out["name"] != "baza.xlsx"
+    assert (root / "baza.xlsx").exists() and (root / out["path"]).exists()
+
+
+# ── kasowanie ────────────────────────────────────────────────────────────
+
+def test_delete_removes_the_file_and_its_entry(root):
+    _xlsx(root / "a.xlsx")
+    files.set_status(root, "a.xlsx", files.ACTIVE)
+    files.delete(root, "a.xlsx")
+    assert not (root / "a.xlsx").exists()
+    assert files.registry(root, for_admin=True) == []
+    assert files.usable_paths(root) == []
+
+
+# ── przejście na rejestr nie może wyłączyć wyszukiwania ─────────────────
+
+def test_bases_already_on_the_share_stay_in_use_after_the_switch(root):
+    """Dotąd bazy działały domyślnie (wyłączało się je przez DISABLED_BASES).
+    Po przejściu na rejestr pusty stan oznaczałby, że program nagle niczego nie
+    znajduje — cicha zmiana zachowania gorsza od awarii, bo wygląda jak pusta baza."""
+    _xlsx(root / "main_base.xlsx")
+    _xlsx(root / "zodiac_pl.xlsx")
+    assert len(files.usable_paths(root)) == 2, "zastane bazy wypadły z wyszukiwania"
+    assert all(e["in_use"] for e in files.registry(root))
+
+
+def test_adoption_happens_once_and_respects_later_decisions(root):
+    """Po przyjęciu stan jest zapisany, więc świadome odstawienie bazy ZOSTAJE —
+    kolejny odczyt nie może jej wskrzesić."""
+    _xlsx(root / "a.xlsx")
+    _xlsx(root / "b.xlsx")
+    files.registry(root)                                   # przyjęcie
+    files.set_status(root, "a.xlsx", files.READY)           # świadome odstawienie
+    assert [pathlib.Path(p).name for p in files.usable_paths(root)] == ["b.xlsx"]
+    files.set_status(root, "b.xlsx", files.READY)           # odstawiamy wszystko
+    assert files.usable_paths(root) == [], "pusty wybór został wskrzeszony"
+
+
+def test_uploaded_files_still_need_an_explicit_switch_on(root):
+    """Przyjęcie dotyczy TYLKO baz zastanych. Plik wgrany ekranem ktoś musi
+    świadomie włączyć — inaczej nowa baza wchodziłaby do wyników sama."""
+    _xlsx(root / "zastana.xlsx")
+    files.registry(root)
+    out = files.store_upload(root, "nowa.xlsx", _xlsx(root / "tmp.xlsx").read_bytes())
+    assert out["accepted"] is True
+    names = [pathlib.Path(p).name for p in files.usable_paths(root)]
+    assert "nowa.xlsx" not in names, "wgrana baza weszła do wyników bez decyzji"
+
+
+def test_adoption_survives_a_read_only_share(root, monkeypatch):
+    """Na udziale tylko do odczytu stanu nie da się zapisać — zachowanie ma
+    zostać to samo, tylko przyjęcie powtórzy się przy każdym uruchomieniu."""
+    _xlsx(root / "a.xlsx")
+
+    def boom(*a, **kw):
+        raise OSError("read-only file system")
+
+    monkeypatch.setattr(files, "_write_state", boom)
+    assert len(files.usable_paths(root)) == 1

services/data/tests/test_rejestr_integracja.py

@@ -0,0 +1,189 @@
+"""Rejestr plików a RESZTA warstwy danych — punkty styku (DAN-27).
+
+DLACZEGO OSOBNY PLIK. test_files.py sprawdza sam rejestr w izolacji i przechodził
+na zielono, podczas gdy na produkcji leżało wyszukiwanie (500) i lista baz (502).
+Rejestr wszedł w miejsce starego mechanizmu włączania baz, więc groźne jest nie
+to, co robi w środku, tylko czy MÓWI TYM SAMYM JĘZYKIEM, co jego odbiorcy.
+
+Oba tamte błędy były jednolinijkowe i oba niewidoczne dla testów jednostkowych:
+  * NameError, bo przepisując `_enabled_files` usunąłem lokalny import `bases`,
+  * KeyError, bo rejestr oddawał `in_use`, a endpoint /bases czytał `enabled`.
+"""
+import pathlib
+
+import pytest
+
+
+@pytest.fixture()
+def excel_dir(tmp_path, monkeypatch):
+    monkeypatch.setenv("EXCEL_DIR", str(tmp_path))
+    monkeypatch.setenv("CACHE_DIR", str(tmp_path / ".cache"))
+    monkeypatch.delenv("DISABLED_BASES", raising=False)
+    monkeypatch.delenv("FILES_STATE", raising=False)
+    return tmp_path
+
+
+def _xlsx(path, rows=(("Ma Ari", "odważny"), ("Ve Tau", "zgodny"))):
+    import openpyxl
+
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.append(["significator", "effect"])
+    for r in rows:
+        ws.append(list(r))
+    wb.save(path)
+    return path
+
+
+def _provider(excel_dir):
+    from app.config import Settings
+    from app.providers.excel_provider import ExcelDataProvider
+
+    return ExcelDataProvider(Settings())
+
+
+def test_search_does_not_explode_on_the_registry(excel_dir):
+    """Regresja: `_enabled_files` wołało bases.disabled_entries() bez importu,
+    więc KAŻDE wyszukiwanie kończyło się NameError → 500 z warstwy danych."""
+    from app.models import SearchQuery
+
+    _xlsx(excel_dir / "baza.xlsx")
+    p = _provider(excel_dir)
+    p.warmup()
+    out = p.search(SearchQuery(key="significator", value="Ma Ari", exact=False, limit=10))
+    assert out.total >= 1, "zastana baza nie weszła do wyszukiwania"
+
+
+def test_search_still_works_with_disabled_bases_set(excel_dir, monkeypatch):
+    """DISABLED_BASES zostaje jako awaryjne wyłączenie i ma odsiewać DODATKOWO —
+    to właśnie ta gałąź kodu wywalała się na braku importu."""
+    from app.models import SearchQuery
+
+    _xlsx(excel_dir / "a.xlsx")
+    _xlsx(excel_dir / "b.xlsx")
+    monkeypatch.setenv("DISABLED_BASES", "b.xlsx")
+    p = _provider(excel_dir)
+    p.warmup()
+    out = p.search(SearchQuery(key="significator", value="Ma Ari", exact=False, limit=10))
+    assert out.total >= 1
+
+
+def test_registry_speaks_the_language_the_bases_endpoint_reads(excel_dir):
+    """Regresja: endpoint /bases liczy `b["enabled"]`, rejestr oddawał `in_use`.
+    KeyError → 500 z danych → 502 z logiki → „Warstwa logiczna niedostępna"
+    na ekranie Ustawienia."""
+    _xlsx(excel_dir / "baza.xlsx")
+    items = _provider(excel_dir).list_bases()
+    assert items, "lista baz jest pusta"
+    for row in items:
+        for key in ("name", "path", "enabled", "in_use", "size_mb", "modified"):
+            assert key in row, f"brak pola `{key}` — odbiorca dostanie KeyError"
+        assert row["enabled"] == row["in_use"], "dwa pola, jedna prawda"
+
+
+def test_bases_endpoint_answers_end_to_end(excel_dir):
+    """Przez TRASĘ, nie przez dostawcę: to ona wywalała się na produkcji."""
+    _xlsx(excel_dir / "baza.xlsx")
+    import importlib
+
+    from app import main as data_main
+
+    importlib.reload(data_main)
+    body = data_main.bases()
+    assert body["total"] == 1
+    assert body["enabled"] == 1, "zastana baza powinna być włączona po adopcji"
+    assert body["bases"][0]["name"] == "baza.xlsx"
+
+
+def test_switching_a_base_off_is_visible_in_both_places(excel_dir):
+    """Odstawienie bazy ma zniknąć i z wyszukiwania, i z licznika na Ustawieniach."""
+    from app import files
+    from app.models import SearchQuery
+
+    _xlsx(excel_dir / "baza.xlsx")
+    p = _provider(excel_dir)
+    p.warmup()
+    assert p.search(SearchQuery(key="significator", value="Ma Ari", limit=10)).total >= 1
+
+    files.set_status(excel_dir, "baza.xlsx", files.READY)
+    p2 = _provider(excel_dir)
+    p2.warmup()
+    assert p2.search(SearchQuery(key="significator", value="Ma Ari", limit=10)).total == 0
+    assert [b["enabled"] for b in p2.list_bases()] == [False]
+
+
+# ── pule kont: izolacja (PRE-29) ─────────────────────────────────────────
+# Najgroźniejsza rzecz w tej zmianie. Wyciek między pulami jest CICHY: klient
+# zobaczyłby cudze opisy jako własny wynik i nikt by się nie zorientował.
+
+def _pool(root, name, plik, tresc):
+    from app import files
+
+    pula = files.tenant_root(root, name)
+    pula.mkdir(parents=True, exist_ok=True)
+    _xlsx(pula / plik, rows=[(tresc, f"opis {tresc}")])
+    files.registry(pula)                                  # przyjęcie zastanych
+    return pula
+
+
+def test_each_account_sees_only_its_own_files(excel_dir):
+    from app import files
+
+    _pool(excel_dir, "klientA", "a.xlsx", "Ma Ari")
+    _pool(excel_dir, "klientB", "b.xlsx", "Ve Tau")
+
+    a = [e["name"] for e in files.registry(files.tenant_root(excel_dir, "klientA"))]
+    b = [e["name"] for e in files.registry(files.tenant_root(excel_dir, "klientB"))]
+    assert a == ["a.xlsx"] and b == ["b.xlsx"]
+
+
+def test_search_never_reaches_another_account_pool(excel_dir):
+    from app.models import SearchQuery
+
+    _pool(excel_dir, "klientA", "a.xlsx", "Ma Ari")
+    _pool(excel_dir, "klientB", "b.xlsx", "Ve Tau")
+    p = _provider(excel_dir)
+    p.warmup()
+
+    swoje = p.search(SearchQuery(key="significator", value="Ma Ari", limit=10, tenant="klientA"))
+    cudze = p.search(SearchQuery(key="significator", value="Ve Tau", limit=10, tenant="klientA"))
+    assert swoje.total >= 1, "konto nie widzi własnej bazy"
+    assert cudze.total == 0, "konto sięgnęło do puli innego konta"
+
+
+def test_the_query_cache_cannot_serve_one_account_the_answer_of_another(excel_dir):
+    """Bez puli w kluczu cache wynik policzony dla jednego konta trafiłby do
+    drugiego — cicha wymiana treści baz, niewidoczna w logach."""
+    from app.models import SearchQuery
+
+    _pool(excel_dir, "klientA", "a.xlsx", "Ma Ari")
+    _pool(excel_dir, "klientB", "b.xlsx", "Ma Ari")       # TA SAMA szukana wartość
+    p = _provider(excel_dir)
+    p.warmup()
+
+    a = p.search(SearchQuery(key="significator", value="Ma Ari", limit=10, tenant="klientA"))
+    b = p.search(SearchQuery(key="significator", value="Ma Ari", limit=10, tenant="klientB"))
+    assert a.total >= 1 and b.total >= 1
+    assert b.cache != "hit", "odpowiedź dla jednego konta wyszła z cache drugiego"
+
+
+def test_a_crafted_pool_name_cannot_escape_the_share(excel_dir):
+    """Nazwa puli przychodzi z zewnątrz (login), więc „../..” albo ukośnik
+    wyprowadziłyby zapytanie wprost do cudzych baz."""
+    from app import files
+
+    for zlosliwa in ("../..", "../klientB", "/etc", "a/../../b", "..", "."):
+        wynik = files.tenant_root(excel_dir, zlosliwa)
+        assert excel_dir in wynik.parents or wynik == excel_dir, f"ucieczka: {zlosliwa} → {wynik}"
+
+
+def test_no_pool_means_the_whole_share_so_production_is_untouched(excel_dir):
+    """Produkcja nie wie o pulach i ma działać dokładnie jak dotąd."""
+    from app import files
+    from app.models import SearchQuery
+
+    _xlsx(excel_dir / "produkcyjna.xlsx")
+    p = _provider(excel_dir)
+    p.warmup()
+    assert files.tenant_root(excel_dir, "") == excel_dir
+    assert p.search(SearchQuery(key="significator", value="Ma Ari", limit=10)).total >= 1

services/engine-swisseph/Dockerfile

@@ -0,0 +1,34 @@
+# Build wieloetapowy — bo `pyswisseph` to rozszerzenie C bez gotowych wheeli.
+#
+# Na PyPI (2.10.3.2) wheels kończą się na cp311 i obejmują wyłącznie i686/x86_64.
+# Dla Pythona 3.12 oraz dla arm64 pip ZAWSZE kompiluje ze źródeł, a `-slim` nie ma
+# kompilatora — dlatego jednoetapowy build tu padał. Kompilujemy w etapie builder,
+# a do obrazu finalnego wchodzi już tylko gotowy wheel (bez toolchaina).
+
+FROM python:3.12-slim AS builder
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends build-essential \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /build
+COPY requirements.txt .
+RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt
+
+
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY --from=builder /wheels /wheels
+COPY requirements.txt .
+RUN pip install --no-cache-dir --no-index --find-links=/wheels -r requirements.txt \
+ && rm -rf /wheels
+
+COPY . .
+
+# Sanity check na etapie budowania: brak działającego swissepha ma wywalić build,
+# a nie dopiero pierwszy request.
+RUN python -c "import swisseph as swe; swe.set_ephe_path(None); print('swisseph OK', swe.version)"
+
+EXPOSE 8003
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8003"]

services/engine-swisseph/LICENSE

@@ -0,0 +1,19 @@
+Ten komponent (services/engine-swisseph) jest licencjonowany na warunkach
+GNU AFFERO GENERAL PUBLIC LICENSE wersja 3 (AGPL-3.0-or-later).
+
+Powód: linkuje bibliotekę pyswisseph / Swiss Ephemeris (Astrodienst AG), która
+jest udostępniana na zasadzie podwójnego licencjonowania: AGPL-3.0 ALBO płatna
+licencja komercyjna. Wybierając wariant AGPL, ten komponent również jest AGPL.
+
+WAŻNE — IZOLACJA: ten komponent jest celowo wydzielony jako osobny proces/usługa
+i komunikuje się z resztą systemu wyłącznie przez HTTP. Pozostałe komponenty
+projektu (warstwa prezentacji, warstwa logiczna z silnikiem własnym, warstwa
+danych) NIE są dziełem pochodnym tego komponentu ani Swiss Ephemeris i pozostają
+na licencji permisywnej. Ten komponent NIE wchodzi do dystrybucji zamkniętego
+produktu — służy jako wyrocznia walidacyjna / tryb porównawczy (dev/CI).
+
+Pełny tekst licencji AGPL-3.0: https://www.gnu.org/licenses/agpl-3.0.txt
+
+Alternatywa: zamiast wariantu AGPL można nabyć komercyjną licencję Swiss
+Ephemeris od Astrodienst AG — wówczas warunki tego komponentu należy dostosować
+do tej licencji.

services/engine-swisseph/README.md

@@ -0,0 +1,38 @@
+# engine-swisseph (silnik B — AGPL, izolowany)
+
+Osobna, **opcjonalna** usługa będąca drugim silnikiem efemeryd (LOG‑27). Liczy
+pozycje przez **pyswisseph / Swiss Ephemeris** i służy jako **wyrocznia
+walidacyjna / tryb porównawczy** (LOG‑25/26) dla naszego silnika własnego.
+
+## ⚠️ Licencja
+Ten komponent jest **AGPL‑3.0** (bo linkuje Swiss Ephemeris) — patrz [LICENSE](LICENSE).
+Jest **wydzielony jako osobny proces** i wołany przez HTTP, więc nie „zaraża"
+permisywnej reszty systemu. **Nie wchodzi do dystrybucji zamkniętego produktu.**
+
+## API
+- `POST /positions` → `{when_utc, lat, lon, objects?}` → pozycje (ten sam kształt co silnik własny)
+- `GET /health`
+
+Tryb Moshiera (`FLG_MOSEPH`) — bez plików efemeryd, zero konfiguracji.
+
+## Build obrazu
+```bash
+docker compose --profile comparison build engine-swisseph
+```
+Dockerfile jest **wieloetapowy** i to nie jest ozdobnik: `pyswisseph` to rozszerzenie
+C, a na PyPI (2.10.3.2) gotowe wheels kończą się na **cp311** i obejmują wyłącznie
+**i686/x86_64**. Dla Pythona 3.12 oraz dla arm64 pip musi kompilować ze źródeł, więc
+sam `python:3.12-slim` (bez kompilatora) build wywracał. Kompilacja idzie w etapie
+`builder` (`build-essential`), a do obrazu finalnego trafia już tylko gotowy wheel —
+runtime zostaje czysty i mały. Pierwszy build trwa ~1–2 min, kolejne idą z cache warstw.
+
+Build kończy się sanity-checkiem (`import swisseph`), żeby niedziałający silnik
+wykrzaczył build, a nie dopiero pierwszy request.
+
+## Uruchomienie (tylko profil porównawczy / dev / CI)
+```bash
+pip install -r requirements.txt      # wymaga kompilatora C (patrz wyżej)
+uvicorn app.main:app --port 8003
+```
+Następnie w warstwie logicznej ustaw `ENGINE_SWISSEPH_URL=http://localhost:8003`,
+aby włączyć silnik B (tryb dual-run i testy kontraktowe silnika B).

services/engine-swisseph/app/main.py

@@ -0,0 +1,140 @@
+"""engine-swisseph — IZOLOWANA usługa silnika B (AGPL).
+
+UWAGA LICENCYJNA: ta usługa linkuje pyswisseph / Swiss Ephemeris, więc jest
+objęta **AGPL-3.0** i jest licencjonowana osobno (patrz ./LICENSE). Jest celowo
+wydzielona jako osobny proces i wołana przez HTTP — dzięki temu permisywny
+produkt (prezentacja + logika z silnikiem własnym + dane) NIE jest linkowany z
+kodem AGPL i nie podlega jego obowiązkom (LOG-27).
+
+Rola: wyrocznia walidacyjna / tryb porównawczy (LOG-25/26). Nie wchodzi do
+dystrybucji zamkniętej — uruchamiana tylko w profilu porównawczym/dev/CI.
+
+Udostępnia ten sam kontrakt co RemoteEngine po stronie warstwy logicznej.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+import swisseph as swe
+
+# Bez /docs, /redoc i /openapi.json: te trasy oddają KOMPLETNY katalog funkcji —
+# nazwy tras, kształty żądań, listę dostawców modeli — i to każdemu, kto potrafi
+# je otworzyć, bez żadnego logowania. Ochrona zakładek w prezentacji nic nie
+# daje, gdy obok stoi usługa, która sama się spisuje (PRE-27).
+app = FastAPI(title="astrololo · engine-swisseph (AGPL, izolowany)",
+              docs_url=None, redoc_url=None, openapi_url=None)
+
+# Tryb Moshiera: bez plików efemeryd, w pełni samowystarczalny (~0,1\" dokładności).
+_FLAGS = swe.FLG_MOSEPH | swe.FLG_SPEED
+
+_PLANETS = {
+    "Sun": swe.SUN, "Moon": swe.MOON, "Mercury": swe.MERCURY, "Venus": swe.VENUS,
+    "Mars": swe.MARS, "Jupiter": swe.JUPITER, "Saturn": swe.SATURN,
+    "Uranus": swe.URANUS, "Neptune": swe.NEPTUNE, "Pluto": swe.PLUTO,
+    # punkty wirtualne — mean, jak w silniku własnym (parzystość LOG-28)
+    "North Node": swe.MEAN_NODE, "Lilith": swe.MEAN_APOG,
+    # "South Node" obsługiwany pochodnie w /positions: NN + 180°
+}
+DEFAULT_OBJECTS = [
+    "Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn",
+    "Uranus", "Neptune", "Pluto", "North Node", "South Node", "Lilith",
+]
+
+
+class PositionsRequest(BaseModel):
+    when_utc: datetime
+    lat: float = 0.0
+    lon: float = 0.0
+    objects: list[str] | None = None
+
+
+@app.post("/positions")
+def positions(req: PositionsRequest) -> dict:
+    d = req.when_utc
+    ut_hours = d.hour + d.minute / 60.0 + d.second / 3600.0
+    jd = swe.julday(d.year, d.month, d.day, ut_hours)  # czas uniwersalny
+
+    rows = []
+    for name in (req.objects or DEFAULT_OBJECTS):
+        lookup = "North Node" if name == "South Node" else name
+        xx, _retflag = swe.calc_ut(jd, _PLANETS[lookup], _FLAGS)
+        lon, lat, _dist, lon_speed = xx[0], xx[1], xx[2], xx[3]
+        if name == "South Node":
+            lon, lat = lon + 180.0, -lat
+        rows.append({
+            "name": name,
+            "longitude": lon % 360.0,
+            "latitude": lat,
+            "speed": lon_speed,
+            "retrograde": lon_speed < 0,
+        })
+    return {"engine": "swisseph", "positions": rows}
+
+
+# Kody systemów domów w Swiss Ephemeris. Nazwy po LEWEJ są nasze — te same,
+# których używa houses.SYSTEMS w warstwie logicznej — żeby wołający nie musiał
+# znać liter swissepha. Lista celowo pokrywa się 1:1 z naszą: rozjazd oznaczałby,
+# że kontrakt parzystości (LOG-28) przestał obejmować część systemów.
+_HOUSE_CODES = {
+    "whole_sign": b"W", "whole_sign_aries": b"N",
+    "equal": b"E", "equal_mc": b"D",
+    "porphyry": b"O", "vehlow": b"V", "morinus": b"M",
+    "regiomontanus": b"R", "campanus": b"C", "alcabitus": b"B",
+    "topocentric": b"T", "placidus": b"P", "koch": b"K",
+}
+
+# Kolejność, w jakiej swe_houses zwraca punkty w tablicy ascmc.
+_ASCMC = ("Asc", "MC", "ARMC", "Vertex", "equatorial_asc",
+          "co_asc_koch", "co_asc_munkasey", "polar_asc")
+
+
+class HousesRequest(BaseModel):
+    when_utc: datetime
+    lat: float = 0.0
+    lon: float = 0.0
+    system: str = "whole_sign"
+
+
+@app.post("/houses")
+def houses(req: HousesRequest) -> dict:
+    """Cuspy domów i osie policzone przez silnik B — do porównania z własnym.
+
+    Domyka kontrakt parzystości (LOG-28) po stronie domów: dotąd obejmował
+    wyłącznie pozycje obiektów, więc błąd w podziale na domy przechodził przez
+    porównanie silników niezauważony. Błąd w domach jest CICHY — wykres wygląda
+    poprawnie, tylko planety siedzą gdzie indziej — więc akurat tu warto mieć
+    drugie zdanie.
+
+    Placidus i Koch nie istnieją powyżej koła podbiegunowego i swisseph zgłasza
+    tam wyjątek. Oddajemy to jako 422 z czytelnym powodem, a NIE podstawiamy po
+    cichu innego systemu: cicha podmiana jest nie do wykrycia po stronie
+    wołającego, a to on ma zdecydować, co z tym zrobić.
+    """
+    code = _HOUSE_CODES.get(req.system)
+    if code is None:
+        raise HTTPException(422, f"nieznany system domów: {req.system!r} "
+                                 f"(znane: {', '.join(sorted(_HOUSE_CODES))})")
+    d = req.when_utc
+    ut_hours = d.hour + d.minute / 60.0 + d.second / 3600.0
+    jd = swe.julday(d.year, d.month, d.day, ut_hours)
+    try:
+        cusps, ascmc = swe.houses(jd, req.lat, req.lon, code)
+    except Exception as e:                      # poza dziedziną systemu
+        raise HTTPException(
+            422, f"system {req.system!r} nie ma definicji dla φ={req.lat}: {e}") from e
+
+    return {
+        "engine": "swisseph",
+        "system": req.system,
+        "cusps": [{"house": i + 1, "longitude": c % 360.0} for i, c in enumerate(cusps)],
+        "angles": {name: ascmc[i] % 360.0 for i, name in enumerate(_ASCMC)
+                   if i < len(ascmc) and name in ("Asc", "MC", "ARMC", "Vertex")},
+    }
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"engine": "swisseph", "status": "ok", "mode": "moshier", "license": "AGPL-3.0"}

services/engine-swisseph/requirements.txt

@@ -0,0 +1,6 @@
+# UWAGA: pyswisseph (Swiss Ephemeris) jest na licencji AGPL-3.0 — dlatego ta
+# usługa jest wydzielona i licencjonowana osobno (patrz LICENSE). Nie instaluj
+# tego w obrazie permisywnego produktu.
+fastapi>=0.115
+uvicorn[standard]>=0.34
+pyswisseph>=2.10

services/logic/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 8001
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8001"]

services/logic/README.md

@@ -0,0 +1,47 @@
+# Warstwa logiczna (`logic`)
+
+Niezależna usługa pośrednicząca. **W górę** udostępnia API dla prezentacji,
+**w dół** woła warstwę bazodanową. Tu żyją reguły biznesowe — nie w prezentacji
+i nie w bazie.
+
+## API
+- `POST /api/query` → `QueryRequest` → `QueryResponse`
+- `POST /chart/positions` → `{when_utc, lat, lon, house_system?}` → pełny horoskop: pozycje (LOG-01) + osie i domy (LOG-05) + aspekty główne z applying/separating (LOG-06) + opcjonalnie stacje planet (`stations:true`, LOG-03). Zwraca też sektę i 7 Lots hermetycznych z domami (LOG-08). Obiekty: 10 planet + mean NN/SN/Lilith (LOG-02). `house_system`: `whole_sign` (dom.) / `equal` / `porphyry`.
+- `POST /chart/report` → `{when_utc, lat, lon, limit?}` → wynik obliczeń wyszukany w bazie: fasety sygnifikatorów **w znaku / w domu / w aspekcie**, z rozwinięciem skrótów, odsiewaniem duplikatów (ten sam sygnifikator i opis), rankingiem siły (LOG-21) oraz opcją group (grupowanie identycznych opisów)
+- `POST /chart/profections` → `{when_utc, lat, lon, start_age?, count?}` → profekcje roczne: wiek, profektowany Asc, Władca Roku (+MC/Su/Mo) (LOG-10)
+- `POST /chart/return` → `{when_utc, lat, lon, kind, around?}` → Solar/Lunar Return: moment powrotu + pełny horoskop na ten moment (LOG-12)
+- `POST /chart/firdaria` → `{when_utc, lat, lon}` → Firdaria: sekta (dzień/noc), okresy główne i podokresy time-lordów (LOG-11)
+- `POST /chart/timeline` → `{when_utc, lat, lon, from_date, to_date, techniques?}` → zbiorcza oś czasu: profekcje + Solar Return + dyrekcje solar-arc + Firdaria, posortowane (technique | significator | start | exact | end); z interpret=true dopina interpretacje z bazy do dat (LOG-14, 1B->2B)
+- `POST /chart/compare` → jak wyżej → raport różnic dwóch silników (LOG-26; wymaga silnika B)
+- `GET /health` (sprawdza też warstwę bazodanową)
+
+## Silnik efemeryd (LOG-24, „wymienny silnik liczący")
+W `app/engine/` żyje pluggable silnik za interfejsem `EphemerisEngine`:
+- **`SkyfieldEngine`** — własny, permisywny (Skyfield MIT + dane JPL public domain). Domyślny.
+- **`RemoteEngine`** — klient OSOBNEJ, izolowanej usługi `engine-swisseph` (AGPL), używany tylko w trybie porównawczym.
+
+Wybór: `EPHEMERIS_ENGINE=own|swisseph`. Silnik B włącza się przez `ENGINE_SWISSEPH_URL`.
+
+Walidacja (LOG-25/28): `app/engine/compare.py` zestawia oba silniki z progiem tolerancji;
+ten sam kontrakt parzystości obowiązuje każdy silnik. Nasz `SkyfieldEngine` zgadza się
+ze Swiss Ephemeris **co do ~1″** na horoskopie referencyjnym (patrz `tests/`).
+
+```bash
+pip install -r requirements-dev.txt
+PYTHONPATH=. pytest tests -q            # silnik B pomijany, jeśli ENGINE_SWISSEPH_URL nieustawiony
+```
+
+## Zależności w dół
+Zna wyłącznie `DATA_URL` (adres warstwy bazodanowej) i jej kontrakt `/search`.
+Nie wie, czy pod spodem jest Excel czy SQL.
+
+## Uruchomienie
+```bash
+pip install -r requirements.txt
+export DATA_URL=http://localhost:8002
+uvicorn app.main:app --port 8001
+```
+
+## Gdzie rozbudowywać domenę
+`service.py` → `QueryService.handle()`: walidacja wejścia, tłumaczenie zapytania,
+obliczenia i wzbogacanie wyników.

services/logic/app/abbreviations.py

@@ -0,0 +1,60 @@
+"""Rozwijanie skrótów sygnifikatorów do postaci czytelnej (na bazie SIGNIFICATORS KEY).
+
+W bazie zapis jest skrótowy z prefiksem `[` (np. `[Su in [Tau`, `[Sa [conj [Su in 6th H.`).
+Ten moduł zamienia go na tekst czytelny: „Sun in Taurus", „Saturn conjunction Sun
+in 6th house". Słownik pochodzi z pliku SIGNIFICATORS KEY (mały, stabilny — wpięty
+jako built-in; można rozszerzać).
+"""
+from __future__ import annotations
+
+import re
+
+# skrót (bez nawiasu) -> pełna nazwa
+ABBREVIATIONS: dict[str, str] = {
+    # znaki zodiaku
+    "Ari": "Aries", "Tau": "Taurus", "Gem": "Gemini", "Can": "Cancer",
+    "Leo": "Leo", "Vir": "Virgo", "Lib": "Libra", "Sco": "Scorpio",
+    "Sag": "Sagittarius", "Cap": "Capricorn", "Aqu": "Aquarius", "Pis": "Pisces",
+    # planety klasyczne + światła
+    "Su": "Sun", "Mo": "Moon", "Me": "Mercury", "Ve": "Venus",
+    "Ma": "Mars", "Ju": "Jupiter", "Sa": "Saturn",
+    # planety nowożytne
+    "Ur": "Uranus", "Ne": "Neptune", "Pl": "Pluto",
+    # węzły i punkty
+    "NN": "North Node", "SN": "South Node", "Lilith": "Lilith", "Chiron": "Chiron",
+    # osie
+    "Asc": "Ascendant", "Dsc": "Descendant", "MC": "Midheaven", "IC": "Imum Coeli",
+    # Lots (punkty arabskie)
+    "PF": "Part of Fortune", "Fortune": "Part of Fortune", "Spirit": "Lot of Spirit",
+    # aspekty
+    "conj": "conjunction", "sex": "sextile", "sq": "square", "tri": "trine",
+    "opp": "opposition", "semisex": "semisextile", "semisq": "semisquare",
+    "sesquisq": "sesquisquare", "quincunx": "quincunx", "asp": "aspect",
+    # domy jako tokeny [h1..[h12
+    **{f"h{i}": f"{i}th house" for i in range(1, 13)},
+    # ruch
+    "Rx": "retrograde", "R": "retrograde",
+}
+# poprawki nieregularnych liczebników domów
+ABBREVIATIONS.update({"h1": "1st house", "h2": "2nd house", "h3": "3rd house"})
+
+# rozwinięcia słów spoza składni `[`
+_WORDS = {
+    "affl.": "afflicted",
+    "P. Dec.": "parallel of declination",
+    "espec.": "especially",
+}
+
+_TOKEN = re.compile(r"\[([A-Za-z]+)")
+_HOUSE = re.compile(r"(\d+(?:st|nd|rd|th))\s*H\.", re.IGNORECASE)
+
+
+def expand(text: str) -> str:
+    """Zamienia skróty na pełne nazwy; nieznane tokeny zostawia bez nawiasu."""
+    if not text:
+        return text
+    out = _TOKEN.sub(lambda m: ABBREVIATIONS.get(m.group(1), m.group(1)), text)
+    out = _HOUSE.sub(lambda m: f"{m.group(1)} house", out)
+    for k, v in _WORDS.items():
+        out = out.replace(k, v)
+    return out

services/logic/app/clients/data_client.py

@@ -0,0 +1,98 @@
+"""Klient HTTP do warstwy bazodanowej.
+
+Jedyny punkt styku w dół. Gdyby warstwa bazodanowa zmieniła implementację
+(Excel→SQL), tutaj nie zmienia się NIC — kontrakt /search jest stały.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from app import link_crypto
+from app.config import settings
+
+
+def _auth_headers() -> dict[str, str]:
+    """Token międzywarstwowy (LOG-32) — pusty, gdy ochrona wyłączona."""
+    token = os.getenv("INTERNAL_TOKEN", "")
+    return {"X-Astrololo-Token": token} if token else {}
+
+
+def _link() -> link_crypto.Link | None:
+    """Klucz łącza logika↔dane. Czytany przy każdym wywołaniu, bo konfiguracja
+    może się zmienić bez restartu procesu (testy, podmiana sekretu)."""
+    key = link_crypto.key_from_env(link_crypto.ENV_LOGIC_DATA)
+    return link_crypto.Link(key) if key else None
+
+
+class DataClient:
+    """Rozmówca warstwy danych, opcjonalnie ZWIĄZANY Z PULĄ KONTA (PRE-29).
+
+    Pula siedzi w INSTANCJI, nie w sygnaturach metod. Gdyby jechała argumentem,
+    trzeba by ją przeprowadzić przez protokół DataSource i przez build_report —
+    czyli przez kod, który o kontach nie ma prawa nic wiedzieć. A przy okazji
+    każde nowe wywołanie byłoby okazją, żeby o nią zapomnieć i sięgnąć nie tam.
+
+    Puste = cały udział, czyli zachowanie produkcji."""
+
+    def __init__(self, base_url: str | None = None, tenant: str = "") -> None:
+        self.base_url = (base_url or settings.data_url).rstrip("/")
+        self.tenant = tenant or ""
+
+    def search(
+        self,
+        key: str,
+        value: str,
+        exact: bool,
+        limit: int,
+        fields: list[str] | None = None,
+    ) -> dict[str, Any]:
+        payload = {"key": key, "value": value, "exact": exact, "limit": limit,
+                   "fields": fields, "tenant": self.tenant}
+        with httpx.Client(timeout=max(settings.http_timeout, 30.0)) as client:
+            return link_crypto.call_json(client, "POST", f"{self.base_url}/search",
+                                         payload=payload, headers=_auth_headers(),
+                                         link=_link())
+
+    def bases(self) -> dict[str, Any]:
+        """Lista baz na udziale + metaopis (DAN-15) — same metadane, bez treści."""
+        with httpx.Client(timeout=settings.http_timeout) as client:
+            return link_crypto.call_json(client, "GET", f"{self.base_url}/bases",
+                                         headers=_auth_headers(), link=_link())
+
+
+    # ── zarządzanie plikami baz (DAN-27) ────────────────────────────────
+    # Jedna metoda na trasę, bez sprytnego generyka: te wywołania różnią się
+    # skutkiem (odczyt / zapis / skasowanie), a ujednolicenie ich w jedno
+    # `call(path, payload)` zaciera tę różnicę dokładnie tam, gdzie jest ważna.
+
+    def files_list(self, for_admin: bool = False) -> dict[str, Any]:
+        return self._files_post("/files", {"for_admin": for_admin, "tenant": self.tenant})
+
+    def files_status(self, path: str, status: str, by: str = "") -> dict[str, Any]:
+        return self._files_post("/files/status", {"path": path, "status": status, "by": by, "tenant": self.tenant})
+
+    def files_upload(self, filename: str, content_b64: str, by: str = "") -> dict[str, Any]:
+        return self._files_post("/files/upload",
+                                {"filename": filename, "content_b64": content_b64, "by": by, "tenant": self.tenant})
+
+    def files_delete(self, path: str) -> dict[str, Any]:
+        return self._files_post("/files/delete", {"path": path, "tenant": self.tenant})
+
+    def files_rules(self, rules: dict) -> dict[str, Any]:
+        return self._files_post("/files/rules", {"rules": rules, "tenant": self.tenant})
+
+    def _files_post(self, path: str, payload: dict) -> dict[str, Any]:
+        with httpx.Client(timeout=settings.http_timeout) as client:
+            return link_crypto.call_json(client, "POST", f"{self.base_url}{path}",
+                                         payload=payload, headers=_auth_headers(), link=_link())
+
+    def health(self) -> dict[str, Any]:
+        # /health celowo poza szyfrowaniem — pukają tu sondy k8s, które klucza
+        # nie mają, a nie przechodzi tędy nic z baz.
+        with httpx.Client(timeout=settings.http_timeout) as client:
+            r = client.get(f"{self.base_url}/health", headers=_auth_headers())
+            r.raise_for_status()
+            return r.json()

services/logic/app/config.py

@@ -0,0 +1,18 @@
+"""Konfiguracja warstwy logicznej.
+
+Zna TYLKO adres warstwy bazodanowej (w dół). Nie wie nic o jej wnętrzu
+(Excel/SQL/cache).
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Settings:
+    data_url: str = field(default_factory=lambda: os.getenv("DATA_URL", "http://localhost:8002"))
+    http_timeout: float = field(default_factory=lambda: float(os.getenv("HTTP_TIMEOUT", "10")))
+
+
+settings = Settings()

services/logic/app/engine/aspects.py

@@ -0,0 +1,149 @@
+"""Aspekty — kąty między obiektami (LOG-06, wersja: aspekty główne).
+
+Czysta matematyka na policzonych długościach ekliptycznych. Dla każdej pary
+obiektów sprawdzamy, czy ich separacja kątowa mieści się w orbie któregoś z
+aspektów głównych. Applying/separating (aplikacja/separacja) — na później.
+
+Tokeny bazy (z SIGNIFICATORS KEY): [conj, [sex, [sq, [tri, [opp.
+"""
+from __future__ import annotations
+
+MAJOR = {
+    "conjunction": 0.0,
+    "sextile": 60.0,
+    "square": 90.0,
+    "trine": 120.0,
+    "opposition": 180.0,
+}
+# Aspekty POBOCZNE (opcjonalne, PRE-06). Tylko te trzy — bo mają już glify i barwy
+# w warstwie prezentacji (chartwheel) oraz w engine/glyphs.py, więc dokładają się
+# bez ruszania czegokolwiek poza silnikiem. Bazy interpretacyjne zwykle ich nie
+# opisują (brak tokenu w DB_TOKEN), więc trafiają na kosmogram i do tabeli, ale
+# NIE generują faset sygnifikatorów — most po cichu je pomija (significators.py).
+MINOR = {
+    "semisextile": 30.0,
+    "semisquare": 45.0,
+    "quincunx": 150.0,
+}
+DB_TOKEN = {
+    "conjunction": "[conj", "sextile": "[sex", "square": "[sq",
+    "trine": "[tri", "opposition": "[opp",
+}
+PL_NAME = {
+    "conjunction": "koniunkcja", "sextile": "sekstyl", "square": "kwadratura",
+    "trine": "trygon", "opposition": "opozycja",
+}
+LUMINARIES = {"Sun", "Moon"}
+DEFAULT_ORB = 8.0
+LUMINARY_BONUS = 2.0
+
+# Pary sztywno powiązane definicyjnie — kąt między nimi wynika z samej definicji
+# punktu, nie z układu nieba (SN = NN + 180°). Aspekt taki zawsze wychodzi
+# dokładny (orb 0,00°) i nie niesie żadnej informacji astrologicznej, więc
+# wycinamy go z wyników: zaśmieca listę w UI i zjada budżet promptu do LLM.
+RIGID_PAIRS = frozenset({
+    frozenset({"North Node", "South Node"}),
+})
+
+
+def _is_rigid(name_a: str, name_b: str) -> bool:
+    return frozenset({name_a, name_b}) in RIGID_PAIRS
+
+
+def separation(a: float, b: float) -> float:
+    """Najmniejsza separacja kątowa [0,180]."""
+    d = abs(a - b) % 360.0
+    return min(d, 360.0 - d)
+
+
+def _is_applying(la: float, lb: float, sa: float, sb: float, angle: float, dt: float = 0.01) -> bool | None:
+    """Czy aspekt aplikuje (dokładność 0° dopiero nastąpi)?
+
+    Porównujemy odchyłkę od dokładnego kąta teraz i po małym kroku czasu
+    (pozycje przesunięte o prędkość·dt). Malejąca odchyłka = applying.
+    dt celowo małe (0,01 doby), by szybki Księżyc nie „przeskoczył" dokładności.
+    Zwraca None, gdy brak prędkości (nie da się rozstrzygnąć).
+    """
+    if sa is None or sb is None:
+        return None
+    dev_now = abs(separation(la, lb) - angle)
+    dev_next = abs(separation(la + sa * dt, lb + sb * dt) - angle)
+    return dev_next < dev_now
+
+
+def _first_aspect(sep: float, allowed: float, checks: dict) -> tuple[str, float] | None:
+    """Pierwszy aspekt z `checks`, w którego orbie mieści się separacja `sep`."""
+    for asp, angle in checks.items():
+        dev = abs(sep - angle)
+        if dev <= allowed:
+            return asp, round(dev, 2)
+    return None
+
+
+def find_cross_aspects(
+    a_positions: list[dict], b_positions: list[dict],
+    orb: float = DEFAULT_ORB, luminary_bonus: float = LUMINARY_BONUS, minor: bool = False,
+) -> list[dict]:
+    """Aspekty MIĘDZY dwoma horoskopami (synastria, PRE-04): każdy obiekt z A vs
+    każdy obiekt z B (`obj1` = osoba A, `obj2` = osoba B). Statyczne — dwa natale,
+    brak wspólnego czasu, więc bez applying/separating. RIGID_PAIRS nie dotyczy
+    (NN osoby A vs SN osoby B to realny aspekt, nie artefakt definicji)."""
+    checks = {**MAJOR, **MINOR} if minor else MAJOR
+    out: list[dict] = []
+    for a in a_positions:
+        la = a.get("decimal")
+        if la is None:
+            continue
+        for b in b_positions:
+            lb = b.get("decimal")
+            if lb is None:
+                continue
+            allowed = orb + (luminary_bonus if (a["name"] in LUMINARIES or b["name"] in LUMINARIES) else 0.0)
+            m = _first_aspect(separation(float(la), float(lb)), allowed, checks)
+            if m:
+                out.append({"obj1": a["name"], "obj2": b["name"],
+                            "aspect": m[0], "orb": m[1], "allowed": round(allowed, 2)})
+    return out
+
+
+def find_aspects(
+    positions: list[dict], orb: float = DEFAULT_ORB, luminary_bonus: float = LUMINARY_BONUS,
+    minor: bool = False,
+) -> list[dict]:
+    """positions: dicty z 'name', 'decimal' (długość) i opcjonalnie 'speed' (°/dobę).
+
+    Zwraca listę aspektów; gdy znane są prędkości, każdy aspekt ma applying (bool)
+    i skrót 'as': 'A'/'S' (aplikacyjny/separacyjny). Orb i bonus dla świateł są
+    KONFIGUROWALNE (PRE-06); `minor=True` dokłada aspekty poboczne (30/45/150°).
+
+    Pary z RIGID_PAIRS (np. NN/SN) są pomijane — ich kąt jest definicyjny.
+    """
+    checks = {**MAJOR, **MINOR} if minor else MAJOR
+    out: list[dict] = []
+    n = len(positions)
+    for i in range(n):
+        for j in range(i + 1, n):
+            a, b = positions[i], positions[j]
+            if _is_rigid(a["name"], b["name"]):
+                continue
+            la, lb = a.get("decimal"), b.get("decimal")
+            if la is None or lb is None:
+                continue
+            sep = separation(float(la), float(lb))
+            allowed = orb + (luminary_bonus if (a["name"] in LUMINARIES or b["name"] in LUMINARIES) else 0.0)
+            for asp, angle in checks.items():
+                dev = abs(sep - angle)
+                if dev <= allowed:
+                    applying = _is_applying(
+                        float(la), float(lb), a.get("speed"), b.get("speed"), angle
+                    )
+                    row = {
+                        "obj1": a["name"], "obj2": b["name"],
+                        "aspect": asp, "orb": round(dev, 2), "allowed": round(allowed, 2),
+                    }
+                    if applying is not None:
+                        row["applying"] = applying
+                        row["as"] = "A" if applying else "S"
+                    out.append(row)
+                    break  # jedna para = jeden aspekt
+    return out

services/logic/app/engine/base.py

@@ -0,0 +1,24 @@
+"""Interfejs silnika efemeryd (LOG-24).
+
+To jest „wymienny silnik liczący". Dziś realizują go: SkyfieldEngine (własny,
+permisywny, in-process) i RemoteEngine (klient izolowanej usługi swisseph, AGPL).
+Warstwa logiczna woła tylko ten interfejs — nie wie, który silnik liczy.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app.engine.models import ChartMoment, ObjectPosition
+
+
+class EphemerisEngine(ABC):
+    name: str = "base"
+
+    @abstractmethod
+    def positions(
+        self, moment: ChartMoment, objects: list[str] | None = None
+    ) -> list[ObjectPosition]:
+        """Pozycje obiektów dla danego momentu (LOG-01). None = zestaw domyślny."""
+
+    def health(self) -> dict:
+        return {"engine": self.name, "status": "ok"}

services/logic/app/engine/chart.py

@@ -0,0 +1,179 @@
+"""Złożenie pełnego horoskopu: pozycje + osie + domy (LOG-01 + LOG-05).
+
+Silnik-agnostyczne: potrzebuje tylko `positions()` oraz (dla osi/domów)
+`sidereal()`. Jeśli silnik nie umie policzyć czasu gwiazdowego, zwraca same
+pozycje.
+"""
+from __future__ import annotations
+
+from app.engine import houses as H
+from app.engine import zodiac as Z
+from app.engine.base import EphemerisEngine
+from app.engine.formats import SIGNS, absolute, decimal, in_sign, norm360, sign_index
+from app.engine.models import ChartMoment
+
+
+def _fmt(name: str, lon: float, off: float = 0.0) -> dict:
+    lon = norm360(lon - off)
+    return {
+        "name": name,
+        "sign": SIGNS[sign_index(lon)],
+        "in_sign": in_sign(lon),
+        "decimal": round(lon, 6),
+    }
+
+
+def _shift_pos(pdict: dict, off: float) -> None:
+    """Przelicza etykiety pozycji na wybrany zodiak (in-place). off=0 → bez zmian."""
+    if not off:
+        return
+    lon = norm360(pdict["decimal"] - off)
+    pdict["sign"] = SIGNS[sign_index(lon)]
+    pdict["in_sign"] = in_sign(lon)
+    pdict["absolute"] = absolute(lon)
+    pdict["decimal"] = decimal(lon)
+
+
+def build_chart(engine: EphemerisEngine, moment: ChartMoment, house_system: str = H.WHOLE_SIGN,
+                lots_method: str = "degree", zodiac: str = Z.TROPICAL,
+                house_systems: list[str] | None = None,
+                aspect_orb: float = 8.0, aspect_luminary_bonus: float = 2.0,
+                aspect_minor: bool = False) -> dict:
+    from app.engine import glyphs as GL
+    from app.engine.aspects import find_aspects
+    from app.engine.houses import mean_obliquity
+    from app.engine.out_of_zodiac import (
+        declination,
+        find_antiscia,
+        find_declination_aspects,
+        is_out_of_bounds,
+    )
+
+    positions = engine.positions(moment)
+    result: dict = {"engine": engine.name, "positions": [p.as_dict() for p in positions]}
+    # aspekty liczymy PRZED zmianą zodiaku — kąty między obiektami są niezmiennicze
+    result["aspects"] = find_aspects(                       # aspekty (LOG-06), konfigurowalne (PRE-06)
+        result["positions"], orb=aspect_orb,
+        luminary_bonus=aspect_luminary_bonus, minor=aspect_minor)
+
+    # Aspekty pozazodiakalne (LOG-07): deklinacja i antyscja liczone na
+    # współrzędnych TROPIKALNYCH of-date — deklinacja jest fizyczna (równikowa),
+    # a antyscja z definicji tropikalna. Dlatego PRZED przesunięciem na zodiak,
+    # z surowych długości/szerokości silnika.
+    # ε PRAWDZIWE — to samo, którym liczymy domy, bo pozycje ze Skyfielda są
+    # POZORNE (uwzględniają nutację). Silnik bez sidereal() nutacji nie poda;
+    # wtedy zostaje średnie, z jawnym oznaczeniem w wyniku.
+    if hasattr(engine, "sidereal"):
+        eps = engine.sidereal(moment)[1]
+        result["obliquity_kind"] = "true"
+    else:
+        eps = mean_obliquity(Z.julian_day(moment.when_utc))
+        result["obliquity_kind"] = "mean"
+    result["obliquity"] = round(eps, 6)
+    for pdict, obj in zip(result["positions"], positions):
+        dec = declination(obj.longitude, obj.latitude, eps)
+        pdict["declination"] = round(dec, 4)
+        if is_out_of_bounds(dec, eps):
+            pdict["out_of_bounds"] = True
+    result["parallels"] = find_declination_aspects(result["positions"])
+    result["antiscia"] = find_antiscia(result["positions"])
+
+    # glify aspektów (LOG-22) — symbol aspektu nie zależy od zodiaku
+    for a in result["aspects"]:
+        a["glyph"] = GL.aspect_glyph(a["aspect"])
+
+    # offset zodiaku (LOG-04): syderyczny = ayanamsa, draconic = długość węzła
+    node_lon = next((p.longitude for p in positions if p.name == "North Node"), None)
+    off = Z.offset(zodiac, Z.julian_day(moment.when_utc), node_lon)
+    result["zodiac"] = zodiac
+    if zodiac in Z.SIDEREAL:
+        result["ayanamsha"] = round(off, 6)
+    for pdict in result["positions"]:
+        _shift_pos(pdict, off)
+
+    # glify obiektów (LOG-22): symbol planety jest niezmienniczy, symbol ZNAKU
+    # zależy od zodiaku, więc po przesunięciu. Pierścień 12 znaków pod kosmogram.
+    for pdict in result["positions"]:
+        pdict["glyph"] = GL.glyph_for(pdict["name"])
+        pdict["sign_glyph"] = GL.sign_glyph(pdict["sign"])
+    result["sign_glyphs"] = [{"sign": s, "glyph": GL.sign_glyph(s)} for s in SIGNS]
+
+    if not hasattr(engine, "sidereal"):
+        return result
+
+    ramc, eps = engine.sidereal(moment)
+    asc = H.compute_asc(ramc, eps, moment.lat)
+    mc = H.compute_mc(ramc, eps)
+    system = house_system if house_system in H.SYSTEMS else H.WHOLE_SIGN
+    # cusps_detailed, nie cusps_for: Placidus i Koch nie istnieją powyżej koła
+    # podbiegunowego, a astrolog z Tromsø ma dostać wynik ZE ŚLADEM, czym go
+    # policzyliśmy. Ten ślad musi dojść aż do raportu i PDF-a.
+    primary = H.cusps_detailed(ramc, eps, moment.lat, system)
+    cusp_list = primary.cusps   # tropikalne — geometria domów jest niezmiennicza
+
+    def _cusps_out(cl: list[float]) -> list[dict]:
+        """Cuspy → wiersze pod UI/kosmogram: znak, stopień w znaku, długość, glif."""
+        return [
+            {"house": i + 1, "sign": SIGNS[sign_index(norm360(c - off))],
+             "in_sign": in_sign(norm360(c - off)),
+             "decimal": round(norm360(c - off), 6),       # długość cuspu — pod kosmogram (PRE-12)
+             "sign_glyph": GL.sign_glyph(SIGNS[sign_index(norm360(c - off))])}
+            for i, c in enumerate(cl)
+        ]
+
+    result["house_system"] = primary.system            # FAKTYCZNIE użyty
+    result["house_system_requested"] = primary.requested
+    # Lista ostrzeżeń dla całego horoskopu — prezentacja, raport i PDF czytają
+    # jedno miejsce, więc żaden z nich nie może „zapomnieć" o fallbacku.
+    result["house_warnings"] = [primary.notice] if primary.notice else []
+    result["angles"] = {
+        "Asc": _fmt("Asc", asc, off),
+        "MC": _fmt("MC", mc, off),
+        "Dsc": _fmt("Dsc", norm360(asc + 180.0), off),
+        "IC": _fmt("IC", norm360(mc + 180.0), off),
+    }
+    for a in result["angles"].values():         # glif znaku osi (LOG-22)
+        a["sign_glyph"] = GL.sign_glyph(a["sign"])
+    result["cusps"] = _cusps_out(cusp_list)      # PRYMARNY system — pod kosmogram i wstecz
+    for pdict, obj in zip(result["positions"], positions):
+        pdict["house"] = H.assign_house(obj.longitude, cusp_list)  # dom po długości tropikalnej
+
+    # Wiele systemów domów NARAZ (PRE-05/LOG-05) — do porównania obok siebie.
+    # Osie (Asc/MC) są wspólne; różni się tylko PODZIAŁ na domy. Prymarny zostaje
+    # w `cusps`/`house_system` (kosmogram i wstecz), a `house_systems` niesie pełen
+    # zestaw; `positions[].houses[system]` mówi, w którym domu obiekt siedzi wg
+    # danego systemu. Dokładamy tylko gdy poproszono o więcej niż jeden.
+    requested = [system] + [s for s in (house_systems or []) if s in H.SYSTEMS]
+    ordered = list(dict.fromkeys(requested))                  # prymarny pierwszy, bez duplikatów
+    if len(ordered) > 1:
+        result["house_systems"] = []
+        for s in ordered:
+            cs = primary if s == system else H.cusps_detailed(ramc, eps, moment.lat, s)
+            block = {"system": s, "used_system": cs.system, "cusps": _cusps_out(cs.cusps)}
+            if cs.notice:
+                block["notice"] = cs.notice
+                if cs.notice not in result["house_warnings"]:
+                    result["house_warnings"].append(cs.notice)
+            result["house_systems"].append(block)
+            for pdict, obj in zip(result["positions"], positions):
+                pdict.setdefault("houses", {})[s] = H.assign_house(obj.longitude, cs.cusps)
+
+    # Lots (LOG-08) — wymagają Asc i sekty (dzień/noc)
+    from app.engine.firdaria import is_day_birth
+    from app.engine.lots import compute_lots
+
+    pts = {p.name: p.longitude for p in positions}
+    pts["Asc"] = asc
+    day = is_day_birth(pts["Sun"], asc, mc) if "Sun" in pts else True
+    result["sect"] = "day" if day else "night"
+    result["lots"] = [
+        {**lot,
+         "longitude": decimal(norm360(lot["longitude"] - off)),   # w wybranym zodiaku
+         "sign": SIGNS[sign_index(norm360(lot["longitude"] - off))],
+         "in_sign": in_sign(norm360(lot["longitude"] - off)),
+         "house": H.assign_house(lot["longitude"], cusp_list),     # dom po długości tropikalnej
+         "glyph": GL.glyph_for(lot["name"]),                       # ⊗ dla Fortuny; reszta None (LOG-22)
+         "sign_glyph": GL.sign_glyph(SIGNS[sign_index(norm360(lot["longitude"] - off))])}
+        for lot in compute_lots(pts, day, lots_method)
+    ]
+    return result

services/logic/app/engine/compare.py

@@ -0,0 +1,104 @@
+"""Harness walidacyjno-porównawczy (LOG-25) i kontrakt parzystości (LOG-28).
+
+`compare_positions` zestawia wyniki dwóch silników z progami tolerancji per
+wielkość i flaguje rozbieżności — używane w testach regresyjnych (CI) i w trybie
+dual-run na żądanie (LOG-26).
+
+`check_engine_contract` to wspólny kontrakt, który MUSI spełnić każdy silnik —
+ten sam test uruchamiamy dla EngineA i EngineB (LOG-28).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from app.engine.base import EphemerisEngine
+from app.engine.models import DEFAULT_OBJECTS, ChartMoment, ObjectPosition
+
+
+def angular_delta(a: float, b: float) -> float:
+    """Najmniejsza różnica kątów w stopniach (z obsługą zawinięcia 0/360)."""
+    return ((a - b + 180.0) % 360.0) - 180.0
+
+
+@dataclass
+class ObjectDiff:
+    name: str
+    lon_a: float
+    lon_b: float
+    delta_arcsec: float        # różnica długości w sekundach łuku
+    lat_delta: float
+    speed_sign_mismatch: bool
+    over_tolerance: bool
+
+
+@dataclass
+class CompareReport:
+    lon_tol_arcsec: float
+    diffs: list[ObjectDiff] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not any(d.over_tolerance or d.speed_sign_mismatch for d in self.diffs)
+
+    @property
+    def max_arcsec(self) -> float:
+        return max((abs(d.delta_arcsec) for d in self.diffs), default=0.0)
+
+    def summary(self) -> dict:
+        return {
+            "ok": self.ok,
+            "objects": len(self.diffs),
+            "max_arcsec": round(self.max_arcsec, 2),
+            "tolerance_arcsec": self.lon_tol_arcsec,
+            "flagged": [d.name for d in self.diffs if d.over_tolerance or d.speed_sign_mismatch],
+        }
+
+
+def compare_positions(
+    a: list[ObjectPosition],
+    b: list[ObjectPosition],
+    lon_tol_arcsec: float = 120.0,
+) -> CompareReport:
+    by_b = {p.name: p for p in b}
+    report = CompareReport(lon_tol_arcsec=lon_tol_arcsec)
+    for pa in a:
+        pb = by_b.get(pa.name)
+        if pb is None:
+            continue
+        d_arcsec = angular_delta(pa.longitude, pb.longitude) * 3600.0
+        report.diffs.append(
+            ObjectDiff(
+                name=pa.name,
+                lon_a=pa.longitude,
+                lon_b=pb.longitude,
+                delta_arcsec=d_arcsec,
+                lat_delta=pa.latitude - pb.latitude,
+                speed_sign_mismatch=(pa.retrograde != pb.retrograde),
+                over_tolerance=abs(d_arcsec) > lon_tol_arcsec,
+            )
+        )
+    return report
+
+
+def compare_engines(
+    engine_a: EphemerisEngine,
+    engine_b: EphemerisEngine,
+    moment: ChartMoment,
+    lon_tol_arcsec: float = 120.0,
+) -> CompareReport:
+    return compare_positions(
+        engine_a.positions(moment), engine_b.positions(moment), lon_tol_arcsec
+    )
+
+
+def check_engine_contract(engine: EphemerisEngine, moment: ChartMoment) -> None:
+    """Kontrakt parzystości (LOG-28). Rzuca AssertionError przy naruszeniu."""
+    positions = engine.positions(moment)
+    names = {p.name for p in positions}
+    assert set(DEFAULT_OBJECTS) <= names, f"brakuje obiektów: {set(DEFAULT_OBJECTS) - names}"
+    for p in positions:
+        assert 0.0 <= p.longitude < 360.0, f"{p.name}: długość poza zakresem ({p.longitude})"
+        assert -90.0 <= p.latitude <= 90.0, f"{p.name}: szerokość poza zakresem ({p.latitude})"
+        assert p.retrograde in (True, False)
+        d = p.as_dict()
+        assert d["sign"] and d["in_sign"], f"{p.name}: brak formatów"

services/logic/app/engine/factory.py

@@ -0,0 +1,30 @@
+"""Fabryka silników (LOG-24) — jedyne miejsce znające konkretne implementacje.
+
+EPHEMERIS_ENGINE = own (domyślnie, permisywny Skyfield) | swisseph (zdalny AGPL).
+`available_engines()` zwraca to, co da się dziś uruchomić — używane przez
+harness porównawczy i testy parzystości.
+"""
+from __future__ import annotations
+
+import os
+
+from app.engine.base import EphemerisEngine
+
+
+def build_engine(name: str | None = None) -> EphemerisEngine:
+    name = (name or os.getenv("EPHEMERIS_ENGINE", "own")).lower()
+    if name in ("swisseph", "remote", "b"):
+        from app.engine.remote_engine import RemoteEngine
+
+        return RemoteEngine()
+    from app.engine.skyfield_engine import SkyfieldEngine
+
+    return SkyfieldEngine()
+
+
+def available_engines() -> dict[str, EphemerisEngine]:
+    """Silniki gotowe do użycia teraz (own zawsze; swisseph jeśli skonfigurowany)."""
+    engines: dict[str, EphemerisEngine] = {"own": build_engine("own")}
+    if os.getenv("ENGINE_SWISSEPH_URL"):
+        engines["swisseph"] = build_engine("swisseph")
+    return engines

services/logic/app/engine/firdaria.py

@@ -0,0 +1,57 @@
+"""Firdaria (LOG-11) — perska technika time-lord.
+
+Sekwencja okresów głównych zależy od sekty (dzień/noc). Sekta: urodzenie dzienne,
+gdy Słońce jest nad horyzontem, czyli po tej samej stronie osi Asc–Dsc co MC.
+
+Klasyczne długości okresów (lata): Su 10, Ve 8, Me 13, Mo 9, Sa 11, Ju 12, Ma 7
+(razem 70) + Węzeł Północny 3 + Węzeł Południowy 2 = 75 lat. Każdy okres główny
+planety dzieli się na 7 podokresów (sub-lord w tej samej kolejności, cyklicznie).
+Węzły — bez podokresów (najczęstsza konwencja).
+"""
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+DAY_ORDER = ["Sun", "Venus", "Mercury", "Moon", "Saturn", "Jupiter", "Mars"]
+NIGHT_ORDER = ["Moon", "Saturn", "Jupiter", "Mars", "Sun", "Venus", "Mercury"]
+YEARS = {"Sun": 10, "Venus": 8, "Mercury": 13, "Moon": 9,
+         "Saturn": 11, "Jupiter": 12, "Mars": 7}
+NODES = [("North Node", 3), ("South Node", 2)]
+DAYS_PER_YEAR = 365.2422
+
+
+def is_day_birth(sun_lon: float, asc: float, mc: float) -> bool:
+    """Słońce nad horyzontem = ta sama półkula osi Asc–Dsc co MC."""
+    return (((sun_lon - asc) % 360.0) < 180.0) == (((mc - asc) % 360.0) < 180.0)
+
+
+def _date(birth: datetime, years: float) -> str:
+    return (birth + timedelta(days=years * DAYS_PER_YEAR)).date().isoformat()
+
+
+def firdaria(birth: datetime, sun_lon: float, asc: float, mc: float) -> dict:
+    """Pełny rozkład Firdarii: sekta, kolejność, okresy główne i podokresy."""
+    day = is_day_birth(sun_lon, asc, mc)
+    order = DAY_ORDER if day else NIGHT_ORDER
+    majors = [(lord, YEARS[lord]) for lord in order] + NODES
+
+    periods: list[dict] = []
+    age = 0.0
+    for lord, yrs in majors:
+        period = {"lord": lord, "years": yrs,
+                  "start": _date(birth, age), "end": _date(birth, age + yrs)}
+        if lord in YEARS:                                  # planeta -> 7 podokresów
+            sub_len = yrs / 7.0
+            i = order.index(lord)
+            sub_age = age
+            subs: list[dict] = []
+            for k in range(7):
+                sub_lord = order[(i + k) % 7]
+                subs.append({"lord": sub_lord,
+                             "start": _date(birth, sub_age),
+                             "end": _date(birth, sub_age + sub_len)})
+                sub_age += sub_len
+            period["sub"] = subs
+        periods.append(period)
+        age += yrs
+    return {"sect": "day" if day else "night", "order": order, "periods": periods}

services/logic/app/engine/formats.py

@@ -0,0 +1,52 @@
+"""Formatowanie długości ekliptycznej (LOG-01: kilka zapisów).
+
+Astrolog myśli w stopniach/minutach/sekundach w znaku, Excel woli dziesiętne,
+a część technik używa pozycji absolutnej 0–360°. Tu są czyste, bezstanowe
+funkcje konwersji — bez zależności od jakiegokolwiek silnika.
+"""
+from __future__ import annotations
+
+SIGNS = [
+    "Aries", "Taurus", "Gemini", "Cancer", "Leo", "Virgo",
+    "Libra", "Scorpio", "Sagittarius", "Capricorn", "Aquarius", "Pisces",
+]
+SIGN_ABBR = ["Ari", "Tau", "Gem", "Can", "Leo", "Vir",
+             "Lib", "Sco", "Sag", "Cap", "Aqu", "Pis"]
+
+
+def norm360(lon: float) -> float:
+    return lon % 360.0
+
+
+def sign_index(lon: float) -> int:
+    """0 = Aries … 11 = Pisces."""
+    return int(norm360(lon) // 30)
+
+
+def _dms(deg: float) -> tuple[int, int, int]:
+    """Rozkład stopni (>=0) na (°, ', ") z poprawnym przeniesieniem zaokrąglenia."""
+    total = round(deg * 3600)
+    d, rem = divmod(total, 3600)
+    m, s = divmod(rem, 60)
+    return d, m, s
+
+
+def in_sign(lon: float) -> str:
+    """Np. 'Tau 28°12'57\"' — pozycja w znaku."""
+    lon = norm360(lon)
+    idx = sign_index(lon)
+    d, m, s = _dms(lon - idx * 30)
+    if d >= 30:  # zaokrąglenie przekroczyło granicę znaku
+        idx = (idx + 1) % 12
+        d -= 30
+    return f"{SIGN_ABBR[idx]} {d}°{m:02d}'{s:02d}\""
+
+
+def absolute(lon: float) -> str:
+    """Np. '58°12'57\"' — pozycja absolutna 0–360°."""
+    d, m, s = _dms(norm360(lon))
+    return f"{d}°{m:02d}'{s:02d}\""
+
+
+def decimal(lon: float, places: int = 6) -> float:
+    return round(norm360(lon), places)

services/logic/app/engine/glyphs.py

@@ -0,0 +1,177 @@
+"""Konwersja tekst ↔ symbol astrologiczny (LOG-22).
+
+Litery i słowa (Sa Pis 26°08' conj Fortune) ↔ glify (♄ ♓ 26°08' ☌ ⊗). Potrzebne
+pod rysowanie kosmogramu (PRE-12) — planety i znaki na kole rysujemy symbolami.
+
+DWIE zasady z bazy wymagań, obie krytyczne:
+  * DAN-18: TYLKO tekstowy Unicode, NIGDY emoji. Część znaków (zodiak, ♀, ♂) ma
+    domyślnie prezentację emoji — kolorowy kwadrat zamiast czarno-białego glifu,
+    nieczytelny i niesterowalny przez CSS. Wymuszamy prezentację tekstową
+    selektorem wariantu U+FE0E (NIE U+FE0F, który robi odwrotnie).
+  * DAN-17: łańcuch musi znosić dowolny Unicode. Reverse (symbol→tekst)
+    normalizuje wejście, zdejmując selektory wariantu, żeby glif z FE0E i bez
+    dawał ten sam wynik.
+
+Glify zapisane przez \\u — jednoznaczne code-pointy, odporne na zniekształcenia
+edytorów i samodokumentujące (widać, który to znak Unicode).
+"""
+from __future__ import annotations
+
+# selektory wariantu prezentacji
+_TEXT = "︎"      # VS15 — wymusza glif tekstowy (czarno-biały)
+_EMOJI = "️"     # VS16 — prezentacja emoji; NIGDY nie emitujemy, zdejmujemy przy reverse
+
+
+def _t(cp: str) -> str:
+    """Znak z wymuszoną prezentacją tekstową (dokleja VS15)."""
+    return cp + _TEXT
+
+
+# ── planety i światła ────────────────────────────────────────────────────
+# ♀ i ♂ mają wariant emoji → wymuszamy tekst; reszta jest tekstowa domyślnie.
+PLANET = {
+    "Sun": "☉",        # ☉
+    "Moon": "☽",       # ☽
+    "Mercury": "☿",    # ☿
+    "Venus": _t("♀"),  # ♀︎
+    "Mars": _t("♂"),   # ♂︎
+    "Jupiter": "♃",    # ♃
+    "Saturn": "♄",     # ♄
+    "Uranus": "♅",     # ♅
+    "Neptune": "♆",    # ♆
+    "Pluto": "♇",      # ♇
+}
+
+# ── punkty wirtualne ─────────────────────────────────────────────────────
+POINT = {
+    "North Node": "☊",  # ☊
+    "South Node": "☋",  # ☋
+    "Lilith": "⚸",      # ⚸  (Black Moon Lilith)
+    "Chiron": "⚷",      # ⚷
+}
+
+# ── Lots (punkty arabskie) ───────────────────────────────────────────────
+# Standardowy glif ma tylko Fortuna (⊗). Reszta Lotów nie ma powszechnie
+# wspieranego symbolu → zwracamy None i UI pokazuje nazwę.
+LOT = {
+    "Fortune": "⊗",         # ⊗
+    "Part of Fortune": "⊗",
+}
+
+# ── znaki zodiaku (wszystkie mają wariant emoji → wszystkie z VS15) ──────
+_SIGN_CP = {
+    "Aries": "♈", "Taurus": "♉", "Gemini": "♊", "Cancer": "♋",
+    "Leo": "♌", "Virgo": "♍", "Libra": "♎", "Scorpio": "♏",
+    "Sagittarius": "♐", "Capricorn": "♑", "Aquarius": "♒", "Pisces": "♓",
+}
+SIGN = {name: _t(cp) for name, cp in _SIGN_CP.items()}
+
+# ── aspekty (nazwy jak w aspects.py + minor z abbreviations) ─────────────
+ASPECT = {
+    "conjunction": "☌",   # ☌
+    "opposition": "☍",    # ☍
+    "trine": "△",         # △
+    "square": "□",        # □
+    "sextile": "⚹",       # ⚹
+    "semisextile": "⚺",   # ⚺
+    "quincunx": "⚻",      # ⚻
+    "semisquare": "∠",    # ∠
+}
+
+# ── ruch ─────────────────────────────────────────────────────────────────
+RETROGRADE = "℞"          # ℞
+DIRECT = "D"              # zwykłe „D" — brak dedykowanego glifu prostego ruchu
+
+
+# ── forward: nazwa → glif ────────────────────────────────────────────────
+
+def glyph_for(name: str) -> str | None:
+    """Glif obiektu/punktu/Lota po nazwie (jak w silniku). None, gdy brak."""
+    return PLANET.get(name) or POINT.get(name) or LOT.get(name)
+
+
+def sign_glyph(sign: str) -> str | None:
+    return SIGN.get(sign)
+
+
+def aspect_glyph(aspect: str) -> str | None:
+    return ASPECT.get(aspect)
+
+
+# ── reverse: glif → nazwa ────────────────────────────────────────────────
+
+def _strip_variants(g: str) -> str:
+    """Zdejmuje selektory wariantu — glif z FE0E i bez daje ten sam klucz."""
+    return g.replace(_TEXT, "").replace(_EMOJI, "")
+
+
+def _reverse(mapping: dict[str, str]) -> dict[str, str]:
+    # pierwsze wystąpienie wygrywa (Fortune vs Part of Fortune → 'Fortune')
+    out: dict[str, str] = {}
+    for name, g in mapping.items():
+        out.setdefault(_strip_variants(g), name)
+    return out
+
+
+_PLANET_POINT_REV = _reverse({**PLANET, **POINT, **{"Fortune": LOT["Fortune"]}})
+_SIGN_REV = _reverse(SIGN)
+_ASPECT_REV = _reverse(ASPECT)
+
+
+def name_for_glyph(g: str) -> str | None:
+    """Obiekt/punkt po glifie (znosi obecność lub brak selektora wariantu)."""
+    return _PLANET_POINT_REV.get(_strip_variants(g))
+
+
+def sign_for_glyph(g: str) -> str | None:
+    return _SIGN_REV.get(_strip_variants(g))
+
+
+def aspect_for_glyph(g: str) -> str | None:
+    return _ASPECT_REV.get(_strip_variants(g))
+
+
+# ── glifikacja tekstu sygnifikatora (składnia [XX z bazy) ────────────────
+# Nasze sygnifikatory zapisane są tokenami z prefiksem [ (np. „[Sa [conj [PF").
+# glyphify zamienia znane tokeny na glify, resztę zostawia. To druga strona
+# abbreviations.expand: tam token → słowo, tu token → symbol.
+import re as _re
+
+# token po nawiasie (np. „Su", „Tau", „conj", „PF") → glif
+_TOKEN_GLYPH: dict[str, str] = {}
+_ABBR_TO_NAME = {
+    "Su": "Sun", "Mo": "Moon", "Me": "Mercury", "Ve": "Venus", "Ma": "Mars",
+    "Ju": "Jupiter", "Sa": "Saturn", "Ur": "Uranus", "Ne": "Neptune", "Pl": "Pluto",
+    "NN": "North Node", "SN": "South Node", "Lilith": "Lilith", "Chiron": "Chiron",
+    "PF": "Fortune", "Fortune": "Fortune",
+}
+for _abbr, _name in _ABBR_TO_NAME.items():
+    _g = glyph_for(_name)
+    if _g:
+        _TOKEN_GLYPH[_abbr] = _g
+_SIGN_ABBR_NAME = {
+    "Ari": "Aries", "Tau": "Taurus", "Gem": "Gemini", "Can": "Cancer", "Leo": "Leo",
+    "Vir": "Virgo", "Lib": "Libra", "Sco": "Scorpio", "Sag": "Sagittarius",
+    "Cap": "Capricorn", "Aqu": "Aquarius", "Pis": "Pisces",
+}
+for _abbr, _name in _SIGN_ABBR_NAME.items():
+    _TOKEN_GLYPH[_abbr] = SIGN[_name]
+_ASP_ABBR_NAME = {
+    "conj": "conjunction", "opp": "opposition", "tri": "trine", "sq": "square",
+    "sex": "sextile", "semisex": "semisextile", "quincunx": "quincunx", "semisq": "semisquare",
+}
+for _abbr, _name in _ASP_ABBR_NAME.items():
+    if _name in ASPECT:
+        _TOKEN_GLYPH[_abbr] = ASPECT[_name]
+
+_TOKEN_RE = _re.compile(r"\[([A-Za-z]+)")
+
+
+def glyphify(text: str) -> str:
+    """Zamienia tokeny [XX na glify; nieznane zostawia bez zmiany. Dodatkowo
+    »Rx«/»R« → ℞. Nie parsuje stopni — te i tak są czytelne (26°08')."""
+    if not text:
+        return text
+    out = _TOKEN_RE.sub(lambda m: _TOKEN_GLYPH.get(m.group(1), m.group(0)), text)
+    out = _re.sub(r"\bR[x]?\b", RETROGRADE, out)
+    return out

services/logic/app/engine/houses.py

@@ -0,0 +1,587 @@
+"""Osie i domy — czysta matematyka sferyczna (LOG-05).
+
+Bezstanowe funkcje: z lokalnego czasu gwiazdowego (RAMC), nachylenia ekliptyki
+(ε) i szerokości geograficznej (φ) wyliczają Ascendent i MC, a stąd cusps domów
+dla prostych systemów (Whole Sign, Equal, Porphyry). Niezależne od silnika —
+silnik dostarcza tylko RAMC i ε.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from app.engine.formats import SIGN_ABBR, norm360, sign_index  # noqa: F401
+
+WHOLE_SIGN = "whole_sign"
+EQUAL = "equal"
+EQUAL_MC = "equal_mc"                 # równe domy zakotwiczone na MC, nie na Asc
+WHOLE_SIGN_ARIES = "whole_sign_aries"  # znaki jako domy, ale dom I to ZAWSZE Baran
+PORPHYRY = "porphyry"
+# Systemy o ZAMKNIĘTYM wzorze (bez iteracji). Placidus i Koch wymagają rozwiązania
+# iteracyjnego i dochodzą osobno.
+VEHLOW = "vehlow"
+MORINUS = "morinus"
+REGIOMONTANUS = "regiomontanus"
+CAMPANUS = "campanus"
+ALCABITUS = "alcabitus"
+TOPOCENTRIC = "topocentric"
+PLACIDUS = "placidus"
+KOCH = "koch"
+# Systemy WYPUSZCZONE — każdy zweryfikowany wobec Swiss Ephemeris
+# (tests/oracle). Placidus i Koch jako jedyne mają granicę dziedziny:
+# powyżej koła podbiegunowego nie istnieją i podlegają jawnemu fallbackowi.
+SYSTEMS = (WHOLE_SIGN, WHOLE_SIGN_ARIES, EQUAL, EQUAL_MC, PORPHYRY, VEHLOW,
+           MORINUS, REGIOMONTANUS, CAMPANUS, ALCABITUS, TOPOCENTRIC,
+           PLACIDUS, KOCH)
+
+
+def mean_obliquity(tt_jd: float) -> float:
+    """Średnie nachylenie ekliptyki [°] dla daty (Julian TT). Wystarcza do domów."""
+    t = (tt_jd - 2451545.0) / 36525.0
+    arcsec = 84381.448 - 46.8150 * t - 0.00059 * t * t + 0.001813 * t ** 3
+    return arcsec / 3600.0
+
+
+def compute_mc(ramc_deg: float, eps_deg: float) -> float:
+    r, e = math.radians(ramc_deg), math.radians(eps_deg)
+    mc = math.atan2(math.sin(r), math.cos(r) * math.cos(e))
+    return norm360(math.degrees(mc))
+
+
+def compute_asc(ramc_deg: float, eps_deg: float, lat_deg: float) -> float:
+    """Ascendent — punkt ekliptyki wschodzący na horyzoncie.
+
+    KOREKTA GAŁĘZI (błąd wykryty przez porównanie z wyrocznią, tests/oracle):
+    ekliptyka przecina horyzont w DWÓCH punktach — wschodzącym (Asc) i zachodzącym
+    (Dsc). `atan2` wybiera jeden z nich, ale powyżej koła podbiegunowego potrafi
+    wskazać ten NIEWŁAŚCIWY: dla szerokości 67°+ i szerokiego zakresu RAMC
+    zwracaliśmy Descendent, czyli Ascendent przesunięty o 180°. Skutek nie był
+    subtelny — planety lądowały w PRZECIWNYCH domach dla całej Skandynawii
+    północnej (Tromsø, Rovaniemi, Murmańsk).
+
+    Rozstrzyga położenie względem MC: punkt wschodzący leży zawsze w półkolu
+    (0°, 180°) na wschód od MC. Reguła zweryfikowana na 46 800 przypadkach wobec
+    Swiss Ephemeris — zero rozbieżności.
+    """
+    r, e, phi = math.radians(ramc_deg), math.radians(eps_deg), math.radians(lat_deg)
+    asc = norm360(math.degrees(math.atan2(
+        math.cos(r),
+        -(math.sin(r) * math.cos(e) + math.tan(phi) * math.sin(e)),
+    )))
+    mc = compute_mc(ramc_deg, eps_deg)
+    return norm360(asc + 180.0) if (asc - mc) % 360.0 > 180.0 else asc
+
+
+def _trisect(a: float, b: float) -> tuple[float, float]:
+    """Dwa punkty dzielące łuk a→b (w kierunku zodiaku) na trzy równe części."""
+    span = (b - a) % 360.0
+    return norm360(a + span / 3.0), norm360(a + 2.0 * span / 3.0)
+
+
+# Poniżej tej odległości od granicy znaku traktujemy Ascendent jak leżący DOKŁADNIE
+# na niej. 1e-9° to 3,6 mikrosekundy łuku — o rzędy wielkości poniżej jakiejkolwiek
+# realnej dokładności danych urodzeniowych, więc nie zmienia to żadnego horoskopu.
+_SIGN_SNAP_DEG = 1e-9
+
+
+def _snap_to_sign_boundary(lon: float) -> float:
+    """Przyciąga długość do granicy znaku, gdy jest od niej o włos.
+
+    Whole sign jest NIECIĄGŁY na granicach znaków: różnica 10⁻¹¹° w Ascendencie
+    przerzuca cały dom I o 30°. Bez tego przyciągania ten sam horoskop policzony
+    na innej maszynie mógłby dać inny wynik (wykryte przez porównanie z wyrocznią:
+    nasz Asc = 359,999999999976, swissepha = 1e-10 — ta sama wartość po dwóch
+    stronach granicy Ryby/Baran). Determinizm jest tu ważniejszy niż dosłowność
+    zmiennoprzecinkowa."""
+    nearest = round(lon / 30.0) * 30.0
+    return norm360(nearest) if abs(lon - nearest) < _SIGN_SNAP_DEG else lon
+
+
+def cusps(asc: float, mc: float, system: str) -> list[float]:
+    """Zwraca 12 cusps (długości) domów 1..12."""
+    if system == WHOLE_SIGN:
+        start = sign_index(_snap_to_sign_boundary(asc)) * 30.0
+        return [norm360(start + 30.0 * i) for i in range(12)]
+    if system == EQUAL:
+        return [norm360(asc + 30.0 * i) for i in range(12)]
+    if system == PORPHYRY:
+        dsc, ic = norm360(asc + 180.0), norm360(mc + 180.0)
+        c = [0.0] * 12
+        c[0], c[3], c[6], c[9] = asc, ic, dsc, mc
+        c[1], c[2] = _trisect(asc, ic)      # domy 2,3
+        c[4], c[5] = _trisect(ic, dsc)      # domy 5,6
+        c[7], c[8] = _trisect(dsc, mc)      # domy 8,9
+        c[10], c[11] = _trisect(mc, asc)    # domy 11,12
+        return c
+    raise ValueError(f"nieznany system domów: {system}")
+
+
+def polar_circle(eps_deg: float) -> float:
+    """Szerokość koła podbiegunowego [°] dla danego nachylenia ekliptyki.
+
+    NIE jest to stała 66,56°: ε zmienia się z datą (ok. 23,71° w 370 p.n.e.,
+    23,44° dziś), więc granica przesuwa się o ~0,3° w zakresie dat programu.
+    Powyżej niej stopnie ekliptyki bywają okołobiegunowe — nie wschodzą ani nie
+    zachodzą — przez co systemy oparte na łuku dobowym (Placidus, Koch) tracą
+    definicję."""
+    return 90.0 - abs(eps_deg)
+
+
+# ── geometria wektorowa dla systemów dzielących koła wielkie ─────────────
+# Wzory na te systemy krążą w literaturze w kilku wariantach i łatwo o pomyłkę
+# w gałęzi albo znaku. Liczymy więc WPROST z geometrii: budujemy wektory kierunkowe
+# w układzie równikowym, przecinamy płaszczyzny i dopiero wynik zamieniamy na
+# długość ekliptyczną. Jest to dłuższe, ale jednoznaczne i sprawdzalne.
+
+def _cross(a, b):
+    return (a[1] * b[2] - a[2] * b[1],
+            a[2] * b[0] - a[0] * b[2],
+            a[0] * b[1] - a[1] * b[0])
+
+
+def _dot(a, b):
+    return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+
+
+def _equatorial_to_lon(v, eps_rad: float) -> float:
+    """Wektor w układzie RÓWNIKOWYM → długość ekliptyczna [°]."""
+    x, y, z = v
+    y_ecl = y * math.cos(eps_rad) + z * math.sin(eps_rad)
+    return norm360(math.degrees(math.atan2(y_ecl, x)))
+
+
+def _ecliptic_pole(eps_rad: float):
+    """Biegun ekliptyki (normalna płaszczyzny ekliptyki) w układzie równikowym."""
+    return (0.0, -math.sin(eps_rad), math.cos(eps_rad))
+
+
+def _horizon_north(ramc_rad: float, lat_rad: float):
+    """Punkt północny horyzontu: RA = RAMC+180°, deklinacja = 90°−φ."""
+    return (-math.sin(lat_rad) * math.cos(ramc_rad),
+            -math.sin(lat_rad) * math.sin(ramc_rad),
+            math.cos(lat_rad))
+
+
+# Domy POŚREDNIE (bez osi) i to, po której stronie MC leżą. Domy 11, 12, 2, 3
+# są na wschód od MC (przesunięcie 0–180°), domy 5, 6, 8, 9 — na zachód.
+_INTERMEDIATE = {1: True, 2: True, 4: False, 5: False,
+                 7: False, 8: False, 10: True, 11: True}
+
+
+def _house_circle_cusp(north, q, eps_rad: float, mc: float, east_of_mc: bool) -> float:
+    """Cusp = przecięcie ekliptyki z kołem domu.
+
+    Koło domu przechodzi przez punkty N/S horyzontu oraz przez punkt podziału `q`
+    (na równiku dla Regiomontanusa, na pierwszym wertykale dla Campanusa).
+    Przecięcie dwóch płaszczyzn daje PROSTĄ, czyli DWA antypodyczne kierunki;
+    wybieramy ten po właściwej stronie południka.
+
+    Używane WYŁĄCZNIE dla domów pośrednich. Osie (1, 4, 7, 10) znamy dokładnie
+    z Asc i MC — liczenie ich tą drogą było błędem, bo leżą dokładnie na granicy
+    „wschód/zachód" (przesunięcie 0° i 180°), gdzie porównanie zmiennoprzecinkowe
+    się chwieje i potrafi wybrać przeciwny punkt nieba."""
+    normal = _cross(north, q)                 # normalna płaszczyzny koła domu
+    line = _cross(normal, _ecliptic_pole(eps_rad))
+    lon = _equatorial_to_lon(line, eps_rad)
+    return lon if ((lon - mc) % 360.0 < 180.0) == east_of_mc else norm360(lon + 180.0)
+
+
+def _culminating_mc(mc: float, eps: float, lat: float) -> float:
+    """Punkt południka, który dla tej szerokości leży NAD horyzontem.
+
+    Systemy oparte na horyzoncie (Regiomontanus, Campanus, Topocentric) biorą jako
+    dziesiąty dom punkt GÓRUJĄCY, a nie matematyczne MC — a za kołem podbiegunowym
+    to nie zawsze to samo. Punkt południka o deklinacji δ ma wysokość 90−|φ−δ|,
+    więc jest nad horyzontem dokładnie wtedy, gdy |φ−δ| < 90.
+
+    Systemy dzielące samą ekliptykę (porphyry, equal, alcabitus, whole sign) tego
+    nie robią — i tak samo zachowuje się wyrocznia."""
+    dec = math.degrees(math.asin(math.sin(math.radians(mc)) * math.sin(math.radians(eps))))
+    return norm360(mc + 180.0) if abs(lat - dec) > 90.0 else mc
+
+
+def _with_exact_angles(intermediate, asc: float, mc: float) -> list[float]:
+    """Składa 12 cuspów: osie wstawione dokładnie, reszta z geometrii."""
+    out = [0.0] * 12
+    out[0], out[3] = asc, norm360(mc + 180.0)      # Asc, IC
+    out[6], out[9] = norm360(asc + 180.0), mc      # Dsc, MC
+    for i, value in intermediate.items():
+        out[i] = value
+    return out
+
+
+def _ra_to_ecliptic_lon(ra_deg: float, eps_rad: float) -> float:
+    """Punkt ekliptyki o zadanej rektascensji (koło godzinne → ekliptyka)."""
+    r = math.radians(ra_deg)
+    return norm360(math.degrees(math.atan2(math.sin(r), math.cos(r) * math.cos(eps_rad))))
+
+
+def _equator_point(ra_deg: float):
+    """Kierunek punktu na równiku niebieskim o danej rektascensji."""
+    r = math.radians(ra_deg)
+    return (math.cos(r), math.sin(r), 0.0)
+
+
+def _prime_vertical_point(ramc_rad: float, lat_rad: float, angle_deg: float):
+    """Punkt pierwszego wertykału, `angle_deg` od punktu wschodu w stronę nadiru.
+
+    Pierwszy wertykał to koło przez wschód, zenit, zachód i nadir — Campanus dzieli
+    właśnie je."""
+    east = (-math.sin(ramc_rad), math.cos(ramc_rad), 0.0)
+    zenith = (math.cos(lat_rad) * math.cos(ramc_rad),
+              math.cos(lat_rad) * math.sin(ramc_rad),
+              math.sin(lat_rad))
+    a = math.radians(angle_deg)
+    return tuple(east[i] * math.cos(a) - zenith[i] * math.sin(a) for i in range(3))
+
+
+def _cusps_regiomontanus(ramc: float, eps: float, lat: float,
+                         asc: float, mc: float) -> list[float]:
+    """Równik niebieski dzielony na 12 równych łuków, rzut kołami przez N/S horyzontu."""
+    er, rr, lr = math.radians(eps), math.radians(ramc), math.radians(lat)
+    north = _horizon_north(rr, lr)
+    mid = {i: _house_circle_cusp(north, _equator_point(ramc + 90.0 + 30.0 * i), er, mc, e)
+           for i, e in _INTERMEDIATE.items()}
+    return _with_exact_angles(mid, asc, _culminating_mc(mc, eps, lat))
+
+
+def _cusps_campanus(ramc: float, eps: float, lat: float,
+                    asc: float, mc: float) -> list[float]:
+    """Pierwszy wertykał dzielony na 12 równych łuków, rzut tak samo jak wyżej."""
+    er, rr, lr = math.radians(eps), math.radians(ramc), math.radians(lat)
+    north = _horizon_north(rr, lr)
+    mid = {i: _house_circle_cusp(north, _prime_vertical_point(rr, lr, 30.0 * i), er, mc, e)
+           for i, e in _INTERMEDIATE.items()}
+    return _with_exact_angles(mid, asc, _culminating_mc(mc, eps, lat))
+
+
+def _cusps_morinus(ramc: float, eps: float) -> list[float]:
+    """Równik dzielony od RAMC i rzutowany WPROST na ekliptykę — bez horyzontu.
+
+    Dlatego Morinus jako jedyny nie zależy od szerokości geograficznej, a jego
+    dom I nie pokrywa się z Ascendentem. Uwaga: to ZAMIANA WSPÓŁRZĘDNYCH punktu
+    równika (RA, dec=0) na ekliptyczne, a nie rzut kołem godzinnym — te dwie
+    operacje dają różne wyniki i pomylenie ich kosztowało tu do 5°."""
+    er = math.radians(eps)
+    return [_equatorial_to_lon(_equator_point(ramc + 90.0 + 30.0 * i), er)
+            for i in range(12)]
+
+
+def _cusps_alcabitus(ramc: float, eps: float, asc: float) -> list[float]:
+    """Łuki równika MC→Asc i Asc→IC dzielone na trzy; rzut kołami godzinnymi."""
+    er = math.radians(eps)
+    a = math.radians(asc)
+    ra_asc = norm360(math.degrees(math.atan2(math.sin(a) * math.cos(er), math.cos(a))))
+    day = (ra_asc - ramc) % 360.0             # łuk MC → Asc (domy 11, 12)
+    night = (ramc + 180.0 - ra_asc) % 360.0   # łuk Asc → IC (domy 2, 3)
+
+    ra = [0.0] * 12
+    ra[9] = ramc                              # dom 10 = MC
+    ra[10] = ramc + day / 3.0                 # dom 11
+    ra[11] = ramc + 2.0 * day / 3.0           # dom 12
+    ra[0] = ra_asc                            # dom 1 = Asc
+    ra[1] = ra_asc + night / 3.0              # dom 2
+    ra[2] = ra_asc + 2.0 * night / 3.0        # dom 3
+    for i in range(6):                        # domy 4–9 naprzeciw 10–3
+        ra[i + 3] = ra[(i + 9) % 12] + 180.0
+    return [_ra_to_ecliptic_lon(x, er) for x in ra]
+
+
+# Ułamek szerokości geograficznej użyty jako „biegun" koła domu (Polich–Page).
+# Domy na południku (10 i 4) mają biegun 0 — ich koło to sam południk.
+# Polich–Page: dom pośredni to Ascendent policzony pod własnym „biegunem"
+# tan(P) = tan(φ)·k/3, dla RAMC przesuniętego o pozycję domu. Rodzina jest CIĄGŁA:
+# przy k=0 (biegun 0, przesunięcie −90°) daje MC, przy k=3 (biegun φ, przesunięcie 0)
+# Ascendent, a domy 11 i 12 leżą po drodze.
+#
+# Cała trudność tego systemu siedziała w wyborze gałęzi — dwa koła wielkie
+# przecinają się w dwóch punktach antypodycznych. Heurystyki („po której stronie
+# MC", „w łuku kwadrantu", „wschodnia połowa horyzontu", śledzenie ciągłości
+# krokami) myliły się na 6–11% przypadków powyżej ~70°, bo każda z nich rozstrzyga
+# LOKALNIE, a przy dużych szerokościach kolejność domów potrafi się odwrócić.
+#
+# Rozwiązanie: 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. Zostajemy więc w wektorach, a znak ustalamy RAZ, kotwicząc
+# rodzinę na MC górującym. Stąd zgodność co do zera na całej dziedzinie, bez iteracji
+# i bez zawężania szerokości.
+
+# Dom → (przesunięcie RAMC [°], ułamek bieguna k/3).
+_TOPO_STEP = {10: (-60.0, 1 / 3), 11: (-30.0, 2 / 3),    # domy 11, 12
+              1: (30.0, 2 / 3), 2: (60.0, 1 / 3)}        # domy 2, 3
+
+
+def _cusps_topocentric(ramc: float, eps: float, lat: float,
+                       asc: float, mc: float) -> list[float]:
+    """Ascendenty pod biegunami tan(P) = tan(φ)·k/3, liczone wektorowo.
+
+    Domy 5, 6, 8, 9 bierzemy jako OPOZYCJE domów 11, 12, 2, 3 — to nie skrót,
+    lecz własność konstrukcji: przeciwległe domy leżą na tym samym kole wielkim.
+
+    Kusi, by liczyć to jak Regiomontanusa z podmienioną szerokością — daje wynik
+    bliski, ale nie równy (kilka sekund łuku); wyrocznia rozstrzygnęła na rzecz
+    konstrukcji „ascendent pod biegunem"."""
+    # Cuspy topocentrica są poprawne na CAŁEJ dziedzinie (zgodne z wyrocznią co do
+    # zera), ale powyżej koła podbiegunowego przestają DZIELIĆ OKRĄG: domy nachodzą
+    # na siebie, bo cusp VII (= I + 180°) wypada przed cuspem VI. Przypisanie planety
+    # do domu traci wtedy sens — co potwierdza sama wyrocznia, której swe_house_pos
+    # przeczy tam własnym cuspom (100% zgodności do 62°, 83,9% przy 66°, ok. 50%
+    # przy 72°). Odmawiamy, zamiast zwracać liczbę bez znaczenia.
+    #
+    # To INNY rodzaj granicy niż u Placidusa i Kocha: tam nie istnieją same cuspy,
+    # tu istnieją, tylko nie tworzą podziału. Próg jest wyprowadzony z warunku
+    # „dwanaście cuspów sumuje się do 360°", nie dobrany pod wynik testu — i wypada
+    # na kole podbiegunowym (zmierzone: 100% podziałów do 65°, 78% w pasie 66-67°).
+    if abs(lat) >= polar_circle(eps):
+        raise HouseSystemUndefined(
+            f"φ={lat:.4f}° powyżej koła podbiegunowego ({polar_circle(eps):.4f}° dla "
+            f"ε={eps:.4f}°): cuspy topocentryczne przestają dzielić okrąg, "
+            f"domy nachodzą na siebie")
+    er, tan_lat = math.radians(eps), math.tan(math.radians(lat))
+    epole = _ecliptic_pole(er)
+    # Gdy MC górujące rozjeżdża się z matematycznym (za kołem podbiegunowym),
+    # cała rodzina obraca się razem z dziesiątym domem — stąd zwrot iloczynu.
+    culminating = _culminating_mc(mc, eps, lat)
+    sign = 1.0 if abs(((culminating - mc + 180.0) % 360.0) - 180.0) > 90.0 else -1.0
+
+    out = [0.0] * 12
+    for i, (offset, fraction) in _TOPO_STEP.items():
+        th = math.radians(ramc + offset)
+        pole = math.atan(tan_lat * fraction)
+        zenith = (math.cos(pole) * math.cos(th),
+                  math.cos(pole) * math.sin(th),
+                  math.sin(pole))
+        v = _cross(zenith, epole)
+        lon = _equatorial_to_lon(tuple(sign * x for x in v), er)
+        out[i] = lon
+        out[(i + 6) % 12] = norm360(lon + 180.0)
+    out[0], out[3] = asc, norm360(culminating + 180.0)
+    out[6], out[9] = norm360(asc + 180.0), culminating
+    return out
+
+
+# ── systemy łuku dobowego (Placidus, Koch) ───────────────────────────────
+# Różnią się od wszystkich poprzednich tym, że NIE MAJĄ wzoru zamkniętego: cusp
+# jest zdefiniowany warunkiem na samego siebie („punkt, który przebył 1/3 swojego
+# półłuku"), więc trzeba go znaleźć iteracyjnie. Mają też jako jedyne REALNĄ
+# granicę dziedziny — powyżej koła podbiegunowego stopnie ekliptyki bywają
+# okołobiegunowe, nie wschodzą ani nie zachodzą, i półłuk po prostu nie istnieje.
+
+
+class HouseSystemUndefined(ValueError):
+    """System domów nie ma definicji dla podanych parametrów (nie: błąd liczenia).
+
+    Podnoszone zamiast zwrócenia liczby, bo cicha podmiana systemu jest gorsza
+    niż błąd: wykres wygląda poprawnie, a planety siedzą w innych domach, niż
+    astrolog zamawiał. Warstwa aplikacyjna łapie to w cusps_detailed() i robi
+    JAWNY fallback."""
+
+
+_ITER_MAX = 100
+_ITER_TOL_DEG = 1e-11
+
+
+def _declination_of_ecliptic_lon(lon_deg: float, eps_rad: float) -> float:
+    """Deklinacja punktu LEŻĄCEGO NA EKLIPTYCE o danej długości."""
+    return math.degrees(math.asin(math.sin(eps_rad) * math.sin(math.radians(lon_deg))))
+
+
+def _ascensional_difference(dec_deg: float, lat_deg: float) -> float:
+    """Różnica wschodnia: o ile półłuk dobowy odbiega od 90°.
+
+    sin(AD) = tan(φ)·tan(δ). Gdy |tan(φ)·tan(δ)| ≥ 1, punkt jest okołobiegunowy
+    (nigdy nie wschodzi albo nigdy nie zachodzi) i półłuk nie istnieje."""
+    v = math.tan(math.radians(lat_deg)) * math.tan(math.radians(dec_deg))
+    if abs(v) >= 1.0:
+        raise HouseSystemUndefined(
+            f"punkt okołobiegunowy (tan φ·tan δ = {v:.6f}): półłuk dobowy nie istnieje")
+    return math.degrees(math.asin(v))
+
+
+# Dom → (ułamek półłuku, czy łuk NOCNY). Domy 11 i 12 dzielą łuk dzienny licząc
+# od MC; domy 2 i 3 — łuk nocny, licząc WSTECZ od IC.
+_PLACIDUS_STEP = {10: (1 / 3, False), 11: (2 / 3, False),
+                  1: (2 / 3, True), 2: (1 / 3, True)}
+
+
+def _placidus_cusp(ramc: float, eps: float, lat: float,
+                   fraction: float, nocturnal: bool) -> float:
+    """Punkt ekliptyki, który przebył `fraction` swojego półłuku.
+
+    Warunek jest uwikłany: półłuk zależy od deklinacji, deklinacja od długości,
+    a długość od położenia — więc iterujemy po punkcie stałym. Zbieżność jest
+    szybka z dala od koła podbiegunowego i psuje się przy nim, dlatego brak
+    zbieżności traktujemy jako wyjście poza dziedzinę, a nie jako wynik."""
+    eps_rad = math.radians(eps)
+    # Start od podziału równomiernego — to Porphyry na równiku, czyli dokładnie
+    # ten przypadek, w którym Placidus się do niego sprowadza.
+    ra = ramc + 180.0 - 90.0 * fraction if nocturnal else ramc + 90.0 * fraction
+    for _ in range(_ITER_MAX):
+        dec = _declination_of_ecliptic_lon(_ra_to_ecliptic_lon(ra, eps_rad), eps_rad)
+        ad = _ascensional_difference(dec, lat)
+        nxt = (ramc + 180.0 - fraction * (90.0 - ad) if nocturnal
+               else ramc + fraction * (90.0 + ad))
+        if abs(nxt - ra) < _ITER_TOL_DEG:
+            return _ra_to_ecliptic_lon(nxt, eps_rad)
+        ra = nxt
+    raise HouseSystemUndefined(
+        f"brak zbieżności po {_ITER_MAX} krokach (φ={lat:.4f}, RAMC={ramc:.4f})")
+
+
+def _cusps_placidus(ramc: float, eps: float, lat: float,
+                    asc: float, mc: float) -> list[float]:
+    """Półłuki dobowe i nocne dzielone na trzy — każdy punkt swoim własnym łukiem."""
+    if abs(lat) >= polar_circle(eps):
+        raise HouseSystemUndefined(
+            f"φ={lat:.4f}° poza kołem podbiegunowym ({polar_circle(eps):.4f}° dla ε={eps:.4f}°)")
+    inter = {i: _placidus_cusp(ramc, eps, lat, f, noct)
+             for i, (f, noct) in _PLACIDUS_STEP.items()}
+    inter.update({(i + 6) % 12: norm360(v + 180.0) for i, v in list(inter.items())})
+    return _with_exact_angles(inter, asc, mc)
+
+
+# Koch dzieli CZAS, nie łuk na niebie. Kryterium: ile czasu minęło od wschodu
+# tego stopnia zodiaku, który stoi na MC. Ten odcinek (półłuk dobowy stopnia MC)
+# dzielimy na trzy i dla punktów podziału liczymy ZWYKŁY Ascendent — stąd nazwa
+# „system miejsca urodzenia". Zgodne z definicją Astrodienst (astro.com/astrowiki).
+#
+# W przeciwieństwie do Placidusa NIE wymaga iteracji: półłuk zależy od deklinacji
+# stopnia MC, którą znamy wprost. Granicę dziedziny dzieli natomiast z Placidusem —
+# gdy stopień MC jest okołobiegunowy, „moment jego wschodu" nie istnieje.
+_KOCH_OFFSET = {10: -2 / 3, 11: -1 / 3, 1: 1 / 3, 2: 2 / 3}
+
+
+def _cusps_koch(ramc: float, eps: float, lat: float,
+                asc: float, mc: float) -> list[float]:
+    """Ascendenty dla chwil trójdzielących drogę stopnia MC od wschodu do górowania."""
+    if abs(lat) >= polar_circle(eps):
+        raise HouseSystemUndefined(
+            f"φ={lat:.4f}° poza kołem podbiegunowym ({polar_circle(eps):.4f}° dla ε={eps:.4f}°)")
+    dec_mc = _declination_of_ecliptic_lon(mc, math.radians(eps))
+    half_arc = 90.0 + _ascensional_difference(dec_mc, lat)
+    inter = {i: compute_asc(ramc + f * half_arc, eps, lat)
+             for i, f in _KOCH_OFFSET.items()}
+    inter.update({(i + 6) % 12: norm360(v + 180.0) for i, v in list(inter.items())})
+    return _with_exact_angles(inter, asc, mc)
+
+
+def cusps_for(ramc: float, eps: float, lat: float, system: str) -> list[float]:
+    """Kanoniczne wejście: (RAMC, ε, φ) → 12 cusps.
+
+    Systemy proste (whole sign / equal / porphyry) potrzebują tylko Asc i MC,
+    ale systemy egzotyczne dzielą inne koła wielkie i wymagają pełnego zestawu
+    (RAMC, ε, φ). Ta funkcja jest wspólnym punktem wejścia dla obu rodzajów —
+    i to ją porównuje z wyrocznią framework testowy (tests/oracle).
+    """
+    asc = compute_asc(ramc, eps, lat)
+    mc = compute_mc(ramc, eps)
+    if system in (WHOLE_SIGN, EQUAL, PORPHYRY):
+        return cusps(asc, mc, system)
+    if system == WHOLE_SIGN_ARIES:
+        # Znaki jako domy, ale numeracja rusza od Barana niezależnie od Ascendentu.
+        # Wariant spotykany w tradycji indyjskiej i w części szkół hellenistycznych.
+        return [norm360(30.0 * i) for i in range(12)]
+    if system == EQUAL_MC:
+        # Równe domy jak `equal`, ale zakotwiczone na MC: dom X zaczyna się
+        # DOKŁADNIE na MC, więc oś południka wypada na granicy domu, a nie w środku.
+        return [norm360(mc + 90.0 + 30.0 * i) for i in range(12)]
+    if system == VEHLOW:
+        # equal, ale Ascendent leży w ŚRODKU domu I, nie na jego początku
+        return [norm360(asc - 15.0 + 30.0 * i) for i in range(12)]
+    if system == MORINUS:
+        return _cusps_morinus(ramc, eps)
+    if system == REGIOMONTANUS:
+        return _cusps_regiomontanus(ramc, eps, lat, asc, mc)
+    if system == CAMPANUS:
+        return _cusps_campanus(ramc, eps, lat, asc, mc)
+    if system == ALCABITUS:
+        return _cusps_alcabitus(ramc, eps, asc)
+    if system == TOPOCENTRIC:
+        return _cusps_topocentric(ramc, eps, lat, asc, mc)
+    if system == PLACIDUS:
+        return _cusps_placidus(ramc, eps, lat, asc, mc)
+    if system == KOCH:
+        return _cusps_koch(ramc, eps, lat, asc, mc)
+    raise ValueError(f"nieznany system domów: {system}")
+
+
+# ── jawny fallback poza dziedziną ────────────────────────────────────────
+# Placidus i Koch jako jedyne mają miejsca, w których po prostu NIE ISTNIEJĄ.
+# Astrolog z Tromsø ma dostać wynik, ale musi wiedzieć, że dostał inny system —
+# cicha podmiana jest gorsza niż brak wyniku, bo jest nie do wykrycia z wykresu.
+
+FALLBACK_SYSTEM = PORPHYRY
+
+
+@dataclass(frozen=True)
+class CuspSet:
+    """12 cuspów + uczciwa informacja, czym naprawdę zostały policzone."""
+
+    cusps: list[float]
+    system: str                          # system FAKTYCZNIE użyty
+    requested: str                       # o który poproszono
+    reason: str | None = None            # dlaczego nie dało się użyć żądanego
+
+    @property
+    def is_fallback(self) -> bool:
+        return self.system != self.requested
+
+    @property
+    def notice(self) -> str | None:
+        """Komunikat dla człowieka. Ma trafić na ekran, do raportu i do PDF-a."""
+        if not self.is_fallback:
+            return None
+        return (f"UWAGA: system domów \u201e{self.requested}\u201d nie ma definicji "
+                f"dla tego miejsca i czasu \u2014 {self.reason}. Domy policzono "
+                f"systemem \u201e{self.system}\u201d. To NIE jest ten sam podzia\u0142: "
+                f"pozycje planet s\u0105 poprawne, ale przypisanie ich do dom\u00f3w "
+                f"pochodzi z innego systemu.")
+
+
+def cusps_detailed(ramc: float, eps: float, lat: float, system: str) -> CuspSet:
+    """Jak cusps_for, ale zamiast wyjątku poza dziedziną robi JAWNY fallback.
+
+    cusps_for zostaje funkcją czystą i nieustępliwą (to ją porównuje wyrocznia);
+    ustępstwo wobec rzeczywistości jest tutaj — i zawsze zostawia ślad."""
+    try:
+        return CuspSet(cusps_for(ramc, eps, lat, system), system, system)
+    except HouseSystemUndefined as e:
+        return CuspSet(cusps_for(ramc, eps, lat, FALLBACK_SYSTEM),
+                       FALLBACK_SYSTEM, system, str(e))
+
+
+def _runs_forward(cusp_list: list[float]) -> bool:
+    """Czy domy biegną w stronę rosnących długości ekliptycznych.
+
+    Zwykle tak — ale NIE ZAWSZE. Przy dużych szerokościach systemy dzielące koła
+    wielkie (regiomontanus, campanus, topocentric) mają kolejność ODWRÓCONĄ:
+    przy φ = −84,3° cusp domu I wypada na 174,2°, a domu II na 165,3°. To nie
+    jest błąd — wyrocznia zwraca dokładnie te same wartości.
+
+    Rozstrzygamy sumą przeskoków „do przodu": dwanaście cuspów dzieli okrąg, więc
+    idąc we WŁAŚCIWĄ stronę zsumują się do 360°. Idąc pod prąd każdy przeskok
+    obchodzi koło dookoła i suma wychodzi 11 × 360° = 3960°."""
+    total = sum((cusp_list[(i + 1) % 12] - cusp_list[i]) % 360.0 for i in range(12))
+    return abs(total - 360.0) < abs(total - 3960.0)
+
+
+def assign_house(lon: float, cusp_list: list[float]) -> int:
+    """Numer domu (1..12), w którym leży dana długość ekliptyczna.
+
+    Kierunek liczenia bierzemy z samych cuspów. Zaszycie „zawsze do przodu"
+    dawało przy |φ| powyżej koła podbiegunowego złe domy dla regiomontanusa,
+    campanusa i topocentrica — mimo cuspów zgodnych z wyrocznią co do zera.
+    Błąd był CICHY: wykres wyglądał poprawnie, tylko planety siedziały gdzie
+    indziej. Sprawdzane wobec swe_house_pos (tests/oracle)."""
+    lon = norm360(lon)
+    forward = _runs_forward(cusp_list)
+    for i in range(12):
+        start = cusp_list[i]
+        end = cusp_list[(i + 1) % 12]
+        if forward:
+            span, offset = (end - start) % 360.0, (lon - start) % 360.0
+        else:
+            span, offset = (start - end) % 360.0, (start - lon) % 360.0
+        if offset < span:
+            return i + 1
+    return 12

services/logic/app/engine/lots.py

@@ -0,0 +1,60 @@
+"""Lots / punkty arabskie (LOG-08) — 7 Lots hermetycznych.
+
+Formuła: Lot = C + A − B (od punktu C odmierzamy odległość między A i B).
+Większość Lots **odwraca się w horoskopach nocnych** (zamiana A↔B) — np.
+Fortuna: dzień Asc + Mo − Su, noc Asc + Su − Mo.
+
+Dwa warianty liczenia (notes3):
+- `degree` (domyślny) — dokładny stopień,
+- `sign` — liczone całymi znakami (Lot wypada na 0° wyliczonego znaku).
+
+Kolejność ma znaczenie: Fortuna i Duch liczone są pierwsze, bo pozostałe Lots
+odwołują się do nich.
+"""
+from __future__ import annotations
+
+from app.engine.formats import norm360, sign_index
+
+# (nazwa, C, A, B, odwracalny w nocy)
+LOT_DEFS: list[tuple[str, str, str, str, bool]] = [
+    ("Fortune",   "Asc", "Moon",    "Sun",     True),
+    ("Spirit",    "Asc", "Sun",     "Moon",    True),
+    ("Eros",      "Asc", "Venus",   "Spirit",  True),
+    ("Necessity", "Asc", "Fortune", "Mercury", True),
+    ("Courage",   "Asc", "Fortune", "Mars",    True),
+    ("Victory",   "Asc", "Jupiter", "Spirit",  True),
+    ("Nemesis",   "Asc", "Fortune", "Saturn",  True),
+]
+
+METHODS = ("degree", "sign")
+
+
+def compute_lots(
+    points: dict[str, float], is_day: bool, method: str = "degree"
+) -> list[dict]:
+    """points: nazwa → długość natalna (wymagane Asc + planety formuł).
+
+    Zwraca listę {name, longitude, formula} w kolejności definicji.
+    """
+    if method not in METHODS:
+        raise ValueError(f"nieznana metoda liczenia Lots: {method}")
+
+    vals = dict(points)
+    out: list[dict] = []
+    for name, c, a, b, reversible in LOT_DEFS:
+        first, second = (a, b) if (is_day or not reversible) else (b, a)
+        if any(k not in vals for k in (c, first, second)):
+            continue                                   # brak składnika — pomijamy
+        if method == "sign":
+            idx = (sign_index(vals[c]) + sign_index(vals[first])
+                   - sign_index(vals[second])) % 12
+            lon = idx * 30.0
+        else:
+            lon = norm360(vals[c] + vals[first] - vals[second])
+        vals[name] = lon                               # dostępny dla kolejnych Lots
+        out.append({
+            "name": name,
+            "longitude": lon,
+            "formula": f"{c} + {first} − {second}",
+        })
+    return out

services/logic/app/engine/models.py

@@ -0,0 +1,66 @@
+"""Modele domenowe silnika efemeryd — wspólny kontrakt dla KAŻDEGO silnika.
+
+To jest część LOG-28 (parzystość): każdy silnik (własny Skyfield czy zdalny
+swisseph) przyjmuje `ChartMoment` i zwraca listę `ObjectPosition` w identycznym
+kształcie i jednostkach. Dzięki temu wyniki są bezpośrednio porównywalne, a
+prezentacja/dane nie wiedzą, który silnik liczył.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from app.engine import formats
+
+# kanoniczny zestaw i kolejność obiektów (LOG-02: światła + 7 klasycznych +
+# 3 nowożytne + punkty wirtualne: węzły mean i mean Lilith)
+DEFAULT_OBJECTS = [
+    "Sun", "Moon", "Mercury", "Venus", "Mars",
+    "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto",
+    "North Node", "South Node", "Lilith",
+]
+
+
+@dataclass(frozen=True)
+class ChartMoment:
+    """Wejście silnika: moment w UTC + lokalizacja geograficzna.
+
+    Pozycje obiektów zależą tylko od czasu (geocentrycznie); szerokość/długość
+    geograficzna będą potrzebne dopiero przy osiach i domach (LOG-05).
+    """
+
+    when_utc: datetime          # musi być świadome strefy (UTC)
+    lat: float = 0.0            # szerokość geograficzna, + na północ
+    lon: float = 0.0           # długość geograficzna, + na wschód
+
+
+@dataclass(frozen=True)
+class ObjectPosition:
+    """Wynik dla jednego obiektu — surowe wartości w jednostkach SI astrologii."""
+
+    name: str
+    longitude: float            # długość ekliptyczna 0–360° (tropikalna, of-date)
+    latitude: float             # szerokość ekliptyczna (°)
+    speed: float                # prędkość w długości (°/dobę)
+    retrograde: bool
+
+    @property
+    def sign(self) -> str:
+        return formats.SIGNS[formats.sign_index(self.longitude)]
+
+    @property
+    def direction(self) -> str:
+        return "Rx" if self.retrograde else "D"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "sign": self.sign,
+            "in_sign": formats.in_sign(self.longitude),
+            "absolute": formats.absolute(self.longitude),
+            "decimal": formats.decimal(self.longitude),
+            "latitude": round(self.latitude, 6),
+            "speed": round(self.speed, 6),
+            "direction": self.direction,
+        }