# Economic Markers In K3s

## Cel

Chcemy dodawac markery ekonomiczne i tradingowe jako osobne komponenty runtime na `mevnode_bot`, bez mieszania ich z samym orderbookiem i bez bezposredniego odpytywania kazdego markera z frontendu.

Docelowy model:

`worker -> Postgres -> Hasura/API -> visualizer`

To ma byc warstwa:

- szybka do rozwijania
- niezalezna per marker
- latwa do obserwacji i debugowania
- bez ryzyka, ze jeden eksperymentalny marker psuje caly runtime

## Zasada architektoniczna

Markery liczymy w osobnych kontenerach na `k3s`, ale nie wystawiamy ich bezposrednio do UI.

Kazdy marker:

1. czyta dane z juz istniejacego runtime:
   - `Hasura`
   - `Postgres`
   - `Redis`
   - opcjonalnie `trade-api`
   - opcjonalnie bezposrednio `mevnode_sol RPC`, jesli marker naprawde tego potrzebuje

2. liczy wlasny sygnal

3. zapisuje wynik do `Postgresa`

4. `Hasura` trackuje tabele markerow

5. `visualizer` rysuje:
   - overlay na chart
   - osobny panel pod chartem
   - badge / regime / warning nad marketem

Frontend nie powinien znac topologii workerow.

## Dlaczego osobne kontenery

To daje kilka korzysci:

- izolacja awarii
- latwe rollouty
- rozne cadence per marker
- mozliwosc wlaczania / wylaczania markerow niezaleznie
- prostszy profiling CPU i memory
- latwiejszy eksperyment workflow

Dobry podzial:

- `fast markers`
  - 200-500 ms
  - mikrostruktura
  - imbalance
  - orderbook slope
  - spread regime

- `medium markers`
  - 1-5 s
  - funding pressure
  - basis
  - depth depletion
  - oracle divergence

- `slow markers`
  - 10-60 s
  - volatility regime
  - realized vol
  - trend regime
  - event calendars

## Rekomendowany model danych

Nie robimy osobnej tabeli per kazdy marker.

Na start lepszy jest wspolny model:

### 1. `market_markers_latest`

Jedna tabela z najnowsza wartoscia markera.

Przyklad kolumn:

- `source`
- `market_name`
- `marker_name`
- `ts`
- `value_num`
- `value_text`
- `value_bool`
- `band`
- `confidence`
- `severity`
- `meta jsonb`
- `updated_at`

Klucz logiczny:

`(source, market_name, marker_name)`

To jest warstwa pod:

- karty market details
- badge typu `risk on`, `thin book`, `high dislocation`
- ostatni stan markera

### 2. `market_markers_ts`

Historia timeseries dla markerow.

Przyklad kolumn:

- `event_ts`
- `id`
- `source`
- `market_name`
- `marker_name`
- `value_num`
- `value_text`
- `value_bool`
- `band`
- `confidence`
- `severity`
- `meta jsonb`
- `inserted_at`

To jest warstwa pod:

- overlaye na chart
- osobne panele
- replay
- debug
- porownanie markerow w czasie

### 3. `market_marker_events`

Opcjonalna tabela tylko dla zmian stanu i alertow.

Przyklad:

- `event_ts`
- `source`
- `market_name`
- `marker_name`
- `event_type`
- `prev_value`
- `next_value`
- `severity`
- `meta`

To jest pod:

- timeline alertow
- debug strategy
- feed zdarzen na UI

## Typy markerow

Najlepiej od razu rozdzielic markery na klasy.

### Overlay markers

To sa serie rysowane bezposrednio na wykresie ceny:

- fair value
- local VWAP
- short-term imbalance line
- oracle divergence bands
- liquidation zones
- micro support / resistance

Dane:

- `value_num`
- opcjonalnie `band`
- opcjonalnie `meta.upper`, `meta.lower`

### Panel markers

To sa osobne serie pod wykresem:

- spread bps
- imbalance
- depth asymmetry
- book velocity
- trade aggression
- realized vol

### State markers

To sa dyskretne stany:

- `trend_up`
- `range`
- `high_risk`
- `thin_liquidity`
- `event_window`

Tu zwykle:

- `value_text`
- `value_bool`
- `severity`
- `confidence`

## Rekomendowane markery na start

Pierwszy pakiet powinien byc maly i praktyczny.

### Marker 1. `oracle_dislocation_bps`

Liczy:

`(mark - oracle) / oracle * 10_000`

Cel:

- pokazac odklejenie od oracle
- ostrzegac, kiedy orderbook/mark zaczyna byc sztucznie przesuniety

Prezentacja:

- panel pod chartem
- badge nad marketem po przekroczeniu progow

### Marker 2. `top12_imbalance`

Liczy:

`(bid_usd - ask_usd) / (bid_usd + ask_usd)`

na poziomach zblizonych do tego, co pokazuje orderbook UI

Cel:

- prosty sygnal przewagi strony
- zgodnosc z tym, co trader widzi na ekranie

Prezentacja:

- panel
- opcjonalnie mini sparkline obok orderbooka

### Marker 3. `spread_regime`

Liczy stan:

- `tight`
- `normal`
- `wide`

na bazie `spread_bps`

Cel:

- szybki filtr, czy rynek nadaje sie do wejscia

Prezentacja:

- badge w market details

### Marker 4. `depth_depletion`

Liczy:

- spadek plynnosci top-of-book vs rolling baseline

Cel:

- wykrywanie, ze ksiazka staje sie pusta zanim ruch przyspieszy

Prezentacja:

- panel
- alert event

### Marker 5. `micro_vol_regime`

Liczy:

- rolling realized volatility na `1s` / `5s` / `1m`

Cel:

- odroznic spokojny market od marketu o zbyt duzym noise

Prezentacja:

- panel pod chartem

## K3s deployment model

Na start proponuje namespace `trade`.

Kazdy marker to osobny `Deployment`, ale z tym samym kontraktem runtime.

Przyklad nazw:

- `marker-oracle-dislocation`
- `marker-top12-imbalance`
- `marker-spread-regime`
- `marker-depth-depletion`
- `marker-micro-vol`

Kazdy deployment:

- `replicas: 1`
- `ConfigMap` dla parametrow
- `Secret` tylko jesli musi czytac cos wrazliwego
- write tylko do Postgresa / Hasury

Nie robimy dla nich publicznych `Service`, jesli nie maja HTTP health/debug endpointu.

Jesli worker ma HTTP:

- tylko `ClusterIP`
- endpointy:
  - `/healthz`
  - `/metrics`
  - `/debug/state`

## Read path dla markerow

Na start marker powinien czytac glownie z durable read modelu:

- `dlob_hot_snapshot_latest`
- `dlob_hot_derived_latest`
- `dlob_hot_derived_ts`
- `dlob_all_derived_latest`
- `dlob_all_derived_ts`
- `dlob_stats_latest`
- `dlob_depth_bps_latest`
- `dlob_slippage_latest`

To daje:

- prostszy kod
- mniej zaleznosci
- zgodnosc z tym, co widzi UI

Bezposredni odczyt z `mevnode_sol RPC` ma sens tylko wtedy, gdy:

- marker potrzebuje point read accountow
- marker potrzebuje szybszego feedu niz Postgres
- marker ma byc trading-critical, a nie tylko UI/debug

## Write path dla markerow

Najbezpieczniejszy model:

- worker liczy marker
- worker robi `upsert` do `market_markers_latest`
- worker robi `insert` do `market_markers_ts`

Opcjonalnie:

- worker emituje event do `market_marker_events`, gdy zmienia sie `band` albo `severity`

## Hasura

Hasura powinna trackowac:

- `market_markers_latest`
- `market_markers_ts`
- `market_marker_events`

Public read:

- tylko wybrane kolumny
- filtr po `market_name`
- opcjonalnie filtr po `marker_name`

To pozwala frontendowi robic:

- subskrypcje latest
- query historii per marker
- timeline eventow

## Visualizer

Visualizer powinien miec trzy tryby prezentacji markerow.

### 1. Overlay na chart

Dla markerow typu line / band:

- `fair value`
- `oracle dislocation bands`
- `micro support`

UI:

- toggle per marker
- wspolny selector `Indicators / Markers`

### 2. Panele pod chartem

Dla markerow oscylatorowych:

- imbalance
- spread bps
- micro vol

UI:

- jeden panel moze pokazywac kilka serii
- albo osobne male panele

### 3. Market badges

Dla stanow:

- `thin book`
- `wide spread`
- `high dislocation`
- `event risk`

UI:

- nad chartem
- nad orderbookiem
- w market details

## Co jest trading-critical, a co research-only

Trzeba to rozdzielic od poczatku.

### Trading-critical

Markery, ktore moga wejsc do decyzji runtime:

- dislocation
- spread regime
- top book depletion
- aggressive imbalance

Dla nich:

- niski latency
- jasne SLA
- monitoring
- alerting

### Research-only

Markery, ktore sa glownie dla obserwacji:

- eksperymentalne composite scores
- event overlays
- egzotyczne oscylatory

Dla nich:

- moga byc liczone wolniej
- moga siedziec w osobnych workerach
- nie powinny blokowac runtime

## Rekomendowany rollout

### Etap 1

Zrobic wspolne tabele:

- `market_markers_latest`
- `market_markers_ts`

oraz trackowanie w Hasurze.

### Etap 2

Uruchomic 2 pierwsze markery:

- `oracle_dislocation_bps`
- `top12_imbalance`

### Etap 3

Dorysowac to w visualizerze:

- 1 overlay
- 1 panel
- 1 badge

### Etap 4

Dopiero potem dodawac kolejne markery.

Nie zaczynac od 10 workerow naraz.

## Kontrakt implementacyjny workerow

Kazdy worker powinien miec:

- jeden glowny loop
- czytelny input set
- czytelny output set
- idempotentny write
- logging per cycle
- proste metryki Prometheus

Minimum metryk:

- `marker_compute_duration_ms`
- `marker_last_success_ts`
- `marker_rows_written_total`
- `marker_failures_total`
- `marker_input_staleness_ms`

## Moja rekomendacja dla tego projektu

Na teraz najlepszy model to:

1. osobne workery markerow w `k3s`
2. wspolne tabele `latest + ts`
3. `Hasura` jako read layer
4. `visualizer` jako warstwa renderu
5. `mevnode_sol RPC` tylko dla markerow, ktore naprawde musza wyjsc poza aktualny read model

To jest wystarczajaco porzadne pod trade, a jednoczesnie nadal lekkie i szybkie do rozwijania.

## Co warto zrobic jutro

1. Dodac SQL dla `market_markers_latest` i `market_markers_ts`.
2. Doliczyc pierwszy marker `oracle_dislocation_bps`.
3. Doliczyc drugi marker `top12_imbalance`.
4. Wystawic obie serie przez Hasure.
5. Narysowac je w visualizerze jako proof of workflow.