docs: add rpc/dlob/candles notes

doc/strategy-eskalacja-horyzontu.md

@@ -0,0 +1,111 @@
+# Strategia: eskalacja horyzontu (1m → 5m → 15m → 30m → 1h) z bramkami ryzyka i kosztów
+
+Cel: jeżeli trade nie domyka celu w krótkim oknie (np. **1m**), możemy **kontrolowanie** przejść na dłuższy horyzont (**5m/15m/30m/1h**) *bez wpadania w “przetrzymanie straty”*.
+
+Klucz: to ma działać jako **state machine** z twardymi bramkami (gates), a nie jako “zostawię i zobaczę”.
+
+---
+
+## 1) Model: “czas na realizację celu” + eskalacja okna
+
+### Parametry (na start)
+- `target_bps` albo `target_usd` (np. +3 bps, +6 bps…)
+- `ttl_per_mode` (time-to-live per tryb):
+  - `1m`: 60–120 s
+  - `5m`: 5–10 min
+  - `15m`: 15–30 min
+  - `30m`: 30–60 min
+  - `1h`: 1–3 h
+
+### Zasada
+Jeśli w danym trybie **nie osiągniesz celu w TTL**, to:
+- albo **zamykanie**,
+- albo **eskalacja** do wyższego okna — *tylko* jeśli spełnione są bramki (ryzyko/koszty/struktura).
+
+---
+
+## 2) Bramki (gates) — kiedy eskalacja jest dozwolona
+
+### Gate RISK (twarde)
+Jeśli którykolwiek warunek jest niespełniony → **wyjście teraz** (close now).
+
+Przykładowe progi:
+- `health >= 0.70`
+- `margin_ratio >= 0.15..0.20` (zależnie od dźwigni)
+- odległość do `liq_price` >= `X%` albo >= `k * ATR`
+- `max_drawdown` w oknie bieżącym nie przekracza limitu
+
+### Gate COSTS (twarde)
+- `close_now_cost_usd` nie “zjada” potencjału (np. koszty nie mogą przekroczyć `target_usd` albo `target_bps`)
+- przy dłuższych trybach (30m/1h) uwzględnij wpływ funding:
+  - `funding_expected(next_window)` nie dominuje nad edge
+
+### Gate STRUCTURE / EDGE (miękkie, ale zalecane)
+Przykłady:
+- trend/edge na wyższym oknie nie jest przeciw (np. 5m dla eskalacji 1m→5m)
+- spread/slippage z DLOB nie rosną anormalnie
+
+---
+
+## 3) Logika przejść (state machine)
+
+Stan początkowy: `mode=1m`.
+
+Jeżeli `ttl_expired` i `target_not_hit`:
+- jeśli `risk_ok && costs_ok && structure_ok` → awans do następnego trybu,
+- inaczej → `close_now`.
+
+Przejścia:
+- `1m` → `5m`
+- `5m` → `15m`
+- `15m` → `30m`
+- `30m` → `1h`
+
+Ważne: awans = **zmiana reżimu** (inne TTL/target/gates), a nie “przeciąganie”.
+
+---
+
+## 4) Pułapka i dwa “hamulce”
+
+Pułapka:
+> “nie poszło w 1m, to poczekam 5m, jak nie to 15m…” → swing bez planu
+
+### Hamulec A: limit eskalacji
+- max 1–2 awanse na trade (np. `1m→5m→15m` i koniec)
+
+### Hamulec B: limit straty per tryb
+- jeśli w trybie 1m strata przekroczy `stop_1m` → wyjście
+- nie wolno “przenosić” tej samej straty w nieskończoność do 1h
+
+---
+
+## 5) Jak to zaszyć w naszym backendzie (worker + API)
+
+W `contract_metrics_ts` (lub w warstwie kontraktu) trzymaj:
+- `mode_current`
+- `mode_enter_ts`
+- `ttl_s_for_mode`
+- `target_bps_for_mode`
+- `gates_passed`:
+  - `risk: boolean`
+  - `costs: boolean`
+  - `structure: boolean`
+- (opcjonalnie) `escalations_used` / `escalations_remaining`
+
+### SIM: “czy eskalacja ma sens”
+Endpoint typu `POST /v1/simulate/escalate` (MVP) może zwracać:
+- `expected_costs` (close now / next window)
+- `risk_after` (health/margin/liq)
+- `assumptions` (np. BBO+extra bps, fee tier)
+
+---
+
+## 6) TL;DR
+
+- Tak, eskalacja czasu ma sens **jeśli jest kontrolowana**.
+- Robimy to jako **state machine** z:
+  - twardym `RISK gate`,
+  - twardym `COST gate`,
+  - limitem eskalacji,
+  - stopem per tryb.
+