# Momentum Service V1

Ten dokument definiuje pierwszy osobny mikroserwis dla bloku `Momentum` z
[bot1.tex](/home/user/dev/trade/doc/bot/bot1.tex).

## Cel

`momentum-service` liczy tylko skladniki momentum i zmiennosci z candles.

Zakres v1:
- `mom_3s`
- `mom_10s`
- `mom_30s`
- `vol_30s`

Poza zakresem v1:
- spread
- depth
- slippage
- gating
- scoring
- zapis decyzji tradingowej

## Zasady

- `Hasura` jest jedynym source of truth dla danych wejsciowych.
- `Fastify` jest shell-em mikroserwisu i wystawia wynik przez endpointy.
- Serwis nie utrzymuje osobnego trwalego stanu prawdy.
- W v1 wynik jest wystawiany przez HTTP i trzymany tylko jako latest runtime snapshot.

## Dlaczego to jest osobny serwis

`momentum-service` jest dobrym deployment boundary, bo caly jego processing zalezy tylko
od candles i nie potrzebuje danych DLOB.

To znaczy:
- `momentum` i `volatility` sa razem w jednym serwisie
- poszczegolne horyzonty `mom_3s`, `mom_10s`, `mom_30s` nie sa osobnymi procesami
- granica serwisu jest wyznaczona przez wspolne wejscie i wspolny wynik runtime, a nie przez pojedynczy wzor

## Wejscie

Serwis czyta z Hasury:
- `bot_config` po `BOT_ID` albo `BOT_NAME`
- `get_drift_candles(...)`

Minimalne dane z `bot_config`:

```json
{
  "market_name": "SOL-PERP",
  "params": {
    "loop": {
      "decision_interval_ms": 1000,
      "candle_bucket_seconds": 1,
      "candles_limit": 64
    },
    "features": {
      "mom_fast_s": 3,
      "mom_mid_s": 10,
      "mom_slow_s": 30,
      "vol_window_s": 30
    }
  }
}
```

## Processing

Model liczenia odpowiada definicjom z `bot1.tex`:

```text
mom_k(t) = 10^4 * (c_t / c_{t-k} - 1)
```

oraz:

```text
vol_W = stddev(r_i), gdzie r_i = 10^4 * (c_i / c_{i-1} - 1)
```

Serwis nie uzywa orderbooka ani tabel derived DLOB.

## Wyjscie

V1 wystawia wynik przez:
- `GET /healthz`
- `GET /readyz`
- `GET /status`
- `GET /result/latest`
- `POST /run`

Przykladowy wynik `GET /result/latest`:

```json
{
  "ok": true,
  "service": "momentum-service",
  "version": "momentum-service-v1",
  "bot": {
    "id": "uuid",
    "name": "sol-observer"
  },
  "market": {
    "name": "SOL-PERP",
    "candle_bucket_seconds": 1,
    "candles_limit": 64
  },
  "features": {
    "mom_3s": 3.8,
    "mom_10s": 6.1,
    "mom_30s": -12.5,
    "vol_30s": 4.2
  },
  "snapshot": {
    "latest_candle_at": "2026-03-27T22:44:10.000Z",
    "candles_count": 64,
    "query_latency_ms": 41,
    "compute_latency_ms": 1
  }
}
```

## Runtime

Petla v1:
- laduje `bot_config`
- pobiera candles
- liczy momentum i volatility
- odswieza `latest result`

Domyslnie:
- loop `1000 ms`
- candles `1s`
- `64` swiece

## Bledy

Serwis zwraca:
- `503` na `/readyz`, gdy nie ma swiezego poprawnego wyniku
- `404` na nieznane endpointy
- `500` na `POST /run`, jesli tick zakonczyl sie bledem

Blad Hasury nie zatrzymuje procesu na stale. Serwis pozostaje online, ale `ready`
przechodzi na `false`, dopoki kolejny poprawny tick nie odswiezy wyniku.

## Relacja do innych serwisow

`momentum-service` jest kandydatem na osobny building block dla:
- `observer-service`
- `scoring-service`
- downstream debug UI

W kolejnych wersjach wynik moze byc:
- nadal tylko czytany przez HTTP,
- albo dodatkowo zapisywany do osobnej tabeli w Hasurze.