docs/architecture.md

# Architecture — 911 Dispatch Supervisor

## Layer Overview
OpenEnvEnvironment          ← public API (reset/step/state/legal_actions)
│
DispatchStateMachine        ← simulation engine
├── DispatchProtocolValidator   ← action legality (15+ rules)
├── RewardCalculator            ← 5-component weighted reward
└── DispatchScenarioFactory     ← deterministic task fixtures
│
Task-Specific Graders          ← episode-level scoring

## Key Design Decisions

### Why Manhattan Distance Physics
Real city blocks use Manhattan (rectilinear) distance for navigation.
Euclidean distance would underestimate travel time by ~27% on average,
making ETAs unrealistically optimistic. Manhattan physics produce ETAs
that match real CAD system calculations.

### Why Legal Actions Are Pre-filtered
Rather than letting agents propose arbitrary actions and penalizing illegal
ones, the environment exposes only currently-valid actions via `legal_actions()`.
This eliminates wasted LLM budget on invalid action generation and focuses
evaluation on dispatch decision quality, not action syntax compliance.

### Why the Safety Gate Uses 0.2 Not 0.0
A hard zero for any P1 failure would make the reward surface completely flat
for bad agents — no gradient to learn from. Capping at 0.2 preserves partial
signal (coverage, response time on other incidents) while making P1 failure
unambiguously catastrophic. Real dispatch accountability works the same way:
an incident review happens, but other good work is still acknowledged.

### Why Phraseology Is Scored
Real dispatchers are evaluated on radio communication clarity. An agent that
dispatches the right unit but says nothing (or says the wrong thing) is less
useful as a CAD copilot than one that also generates the correct radio traffic.
Phraseology scoring creates incentive for agents to learn domain language, not
just resource allocation.

### Why Waves Spawn at Fixed Steps Not Random Times
Reproducibility is a first-class requirement. Fixed step offsets guarantee
identical episode structure across all runs, making score comparisons valid.
The challenge comes from the agent not knowing wave timing in advance — it
must react, not plan.

## State Machine Transitions
Unit:     AVAILABLE → DISPATCHED → ON_SCENE → AVAILABLE
↘️ STAGED     ↗️
Incident: PENDING → RESPONDING → ON_SCENE → RESOLVED
↘️ ESCALATED (survival clock expired)

## File Map

| File | Responsibility |
|---|---|
| `src/models.py` | All Pydantic data contracts |
| `src/state_machine.py` | Core simulation engine |
| `src/protocol.py` | Action legality validation |
| `src/rewards.py` | Reward calculation |
| `src/physics.py` | Manhattan distance, ETA, coverage |
| `src/phraseology.py` | Radio language scoring |
| `src/city_schema.py` | City topology loader |
| `src/tasks/registry.py` | Task definitions and fixtures |
| `src/openenv_environment.py` | OpenEnv API wrapper |
| `server/app.py` | FastAPI server |