Capsule: match history

Use when changing match-history schema, persistence, the /api/matches endpoint, the recording scope, or the lobby front-page table.

Read first

server/src/db.rs — pool, migrations, record_match, recent_matches, replay_artifact_for_match.
server/src/main.rs — env loading, /api/matches, POST /api/matches/{id}/replay, replay compatibility checks, RTS_RECORD_MATCHES public/local scope.
server/src/lobby/mod.rs — Lobby::with_match_history() injects pool/scope into rooms; replay launch creates spectator replay rooms.
server/src/lobby/room_task.rs — capture metadata at start_match, detached write at end_match.
server/migrations/*.sql — versioned schema. Never hand-apply DDL.
client/src/match_history.js — lobby table renderer and replay launch action.
client/src/app.js — mounts/refreshes the table on lobby show / back-to-lobby; auto-joins ?replayRoom=... launch pages.

Server is the only writer. Clients never write history. /api/matches is read-only.
Detached write at end_match. A slow Supabase write must never stall the room. Errors log and are dropped.
Recording scope. Beta/mainline writes are enabled only when RTS_RECORD_MATCHES is truthy. Deployed normal matches, including solo, player-vs-AI, and AI-only matches, get replay-backed rows unless they are dev/scenario/replay rooms or automated test fingerprints. Local cargo run with the gate off can read history but does not upload rows or replay artifacts.
Recent Matches visibility. /api/matches returns only rows with human_count >= 1 and debug_mode = false, so AI-only and lobby Debug/quickstart rows can be stored for replay launch without appearing in the lobby table.
Score-screen schema. score_screen is JSONB holding Vec<PlayerScore> from contract::PlayerScore. Adding fields requires no migration.
Replay storage. match_replays.artifact_json stores ReplayArtifactV1; summaries and launch check artifact schema, build SHA, map schema, and map hash before playback.
TLS to Supabase. DATABASE_URL must include ?sslmode=require.