docs/map/server.md

# Server Map - `server/app.py`

> FastAPI backend with REST + WebSocket endpoints. The normal path now uses
> the real `ReplicaLabEnv`; `_StubEnv` remains only as a fallback if the env
> package cannot be imported.
>
> **Tasks implemented:** API 01-09, 13, 15

## Environment path

### `ReplicaLabEnv`
Primary environment implementation imported from
`replicalab.env.replicalab_env`.

### `_StubEnv`
Legacy fallback kept so the server can still boot if the real env import
fails. It is no longer the intended local or Docker runtime.

### `_make_env()`
Factory that prefers `ReplicaLabEnv` and falls back to `_StubEnv` only on
import failure.

## REST endpoints

### `GET /health`
Returns a liveness payload. When the real env path is active, the response
includes `env: "real"`.

### `POST /reset`
Starts a new episode and returns:

- `session_id`
- `episode_id`
- typed `Observation`

### `POST /step`
Submits a typed `ScientistAction` and returns `StepResult`.

When `done=true`, the terminal `StepResult` is also used to build the replay
log so `reward_breakdown`, `judge_notes`, and `verdict` stay aligned with the
real env result.

### `GET /scenarios`
Returns the available scenario families and supported difficulties.

### `GET /replay/{episode_id}`
Returns the stored `EpisodeLog` for a completed episode or 404 if not found.

## WebSocket endpoint

### `WS /ws`
Per-connection isolated environment session supporting:

- `reset`
- `step`
- `ping`

Idle timeout and disconnect cleanup are implemented and verified.

## Session management

| Store | Purpose |
| --- | --- |
| `_sessions` | Active REST sessions |
| `_replay_store` | Completed episode logs |

## Key helpers

| Function | Purpose |
| --- | --- |
| `_build_episode_log(episode_id, state, result)` | Build replay log from final state and terminal step result |
| `_touch(session_id)` | Refresh REST session last-active timestamp |
| `_cleanup_stale_sessions()` | Remove expired REST sessions |

## Current deployment state

- Local OpenEnv validation passes
- Local Docker build and run verification passes
- HF Spaces metadata is present in the root `README.md` and root `Dockerfile`
- Live hosted verification remains `API 10`