docs/SPEC_AUDIT.md

# Specification audit

Every requirement from the two project documents and the build brief, checked
against what is actually in the repository. Where something is partial or
deliberately not built, it says so.

Legend: **✓** built and verified · **◐** partial, scoped deliberately · **✗** not built

---

## Core loop — SEE → PREDICT → SIMULATE → ACT

| Requirement | Status | Where |
|---|---|---|
| Observe current crowd state | ✓ | `crowd/state.py` — occupancy, density, inflow, outflow, velocity, utilisation, growth, conflict, risk |
| Predict near-term state | ✓ | `prediction/` — trained model + physics baseline, +30/60/90/120 s |
| Simulate candidate interventions | ✓ | `strategy/counterfactual.py` — each candidate on an identical clone |
| Act: recommend and apply | ✓ | `strategy/optimizer.py`, `strategy/engine.py`; operator applies from the UI |
| Observe again — closed loop | ✓ | applying feeds the same simulation; benchmark arm re-reviews on a cycle |

## Simulation

| Requirement | Status | Notes |
|---|---|---|
| Individual agents | ✓ | Structure-of-arrays; 40,000 in the showcase run, 78,000 in Barcelona |
| Origins, destinations, movement, velocity | ✓ | Per-agent speed factor from a clipped normal |
| Routes and route preferences | ✓ | Next-hop tables per policy; three policies |
| Reroute compliance | ✓ | Per agent, sampled per scenario; instructions are refused by some |
| Congestion | ✓ | Weidmann speed–density, evaluated per ~12 m cell |
| Capacity constraints | ✓ | Node service rate and edge throughput, both with fractional carry |
| Changing infrastructure capacity | ✓ | Scripted timeline events; retunable from the What-If panel |
| Event phases | ✓ | Venue phases drive the phase label; scenarios carry a phase timeline |
| Rerouting | ✓ | Adaptive policy adoption with per-agent compliance |
| Visible bottlenecks | ✓ | Verified in the browser and asserted in tests |
| Deterministic seeds | ✓ | RNG state travels with the snapshot; asserted in tests |
| Accelerated execution | ✓ | 1× … 40× |
| 10,000–40,000 agents | ✓ | ~2–4 ms per step at 40,000 |

## Crowd State Engine

Occupancy, density, inflow, outflow, velocity, capacity utilisation, density
growth, queue growth, risk score — **✓** all present, plus opposing-flow conflict
and peak local density. Per-term risk contributions are exposed so alerts can
explain themselves.

## Prediction

| Requirement | Status | Notes |
|---|---|---|
| Genuine prediction layer | ✓ | Gradient boosting, one model per horizon |
| Uses actual simulation state | ✓ | Features come from the Crowd State Engine only |
| "Where will congestion develop in 30/60/90 s" | ✓ | Plus 120 s |
| Strong baseline first, model swappable | ✓ | Analytic mass-balance projection; model used only if it beats it on held-out seeds |
| No faked ML | ✓ | Validation on disjoint seeds, reported in the UI |

## Hugging Face

| Requirement | Status | Notes |
|---|---|---|
| Genuine integration | ✓ | `perception/huggingface.py`, real inference path |
| Camera → HF model → observation → crowd state | ✓ | Shared observation schema |
| Both modes converge | ✓ | `observation_to_zone_state` |
| Documented model choice | ✓ | Candidate chain with the two specification models first; manifest written on load |
| Never fabricates a count | ✓ | Reports the real error instead; asserted in tests |

**Caveat, stated plainly:** the build environment had no network access to
`huggingface.co`, so the chain could not be exercised against live weights here.
The code path, the CSRNet architecture, the manifest and the failure reporting
are all implemented and the endpoint is verified to fail honestly when no model
loads. Run `scripts/fetch_hf_model.py` on a networked machine to download,
select and verify with a real inference.

## Strategy engine

| Requirement | Status |
|---|---|
| Generates candidate interventions | ✓ |
| No action / reroute % / gate stagger / alternate exit / destination split | ✓ |
| Combined interventions | ✓ |
| Set depends on venue topology | ✓ — a reroute needs an alternative path; an alternate exit needs measured spare capacity |

## Counterfactual simulation

Capture state → clone → apply A → simulate → reset → apply B → … → compare →
select. **✓** Implemented exactly, with tests asserting that two branches of one
state produce identical results and that evaluation does not advance the live
run.

## Optimization

Peak density, critical duration, average travel time, queue, throughput,
aggregate risk, unnecessary rerouting — **✓** all seven in `J`, weights
configurable by environment variable, contributions exposed per strategy.
Explanation generated from the same normalised terms that produced the score.

## Dynamic routing

| Requirement | Status |
|---|---|
| Not static shortest path | ✓ |
| Cost responds to distance, travel time, congestion, density, capacity, risk | ✓ |
| Oscillation prevention | ✓ — hysteresis, policy stickiness, cycle-break, asserted in tests |
| Rerouting produces observable change | ✓ — verified in the browser and in tests |

## Simulation 1 — F1 Circuit Stress Test

Fictional venue with 4 gates, 6 spectator zones, 8 concourse corridors, 4 exits,
3 concessions, 2 transport hubs — **✓**. Large post-race crowd, simultaneous
egress, reduced exit capacity — **✓**. The full arc (normal flow → bottleneck →
prediction → strategy evaluation → recommendation → rerouting → recovery) runs
end to end without manual intervention and is verified by `scripts/ui_check.py`.

## Simulation 2 — Barcelona 2022

| Requirement | Status |
|---|---|
| Simplified digital twin of the spectator/transport network | ✓ |
| Circuit, spectator zones, gates, pedestrian routes, exits, parking, transport | ✓ |
| Historical facts separated from assumptions | ✓ — two labelled lists, on screen, each fact with a source |
| Explicit counterfactual disclaimer | ✓ — in the venue data, the briefing and the UI |
| No claim of reproducing telemetry | ✓ — asserted in tests |

## Frontend

Race Control dashboard with event, crowd state, venue map, density, predicted
bottlenecks, alerts, flow direction, simulation status and recommendation — **✓**.
Crowds move; congested zones change colour; routes animate; predicted congestion
is drawn distinctly from current congestion. Strategy simulator with measured
outcomes and a recommended row — **✓**. Explainability panel using actual
calculated values — **✓**.

## Backend & real-time

FastAPI, modular packages (simulation / crowd / prediction / routing / strategy /
perception / api), WebSocket streaming with no per-frame polling, graceful
validation failures — **✓** all present, with API tests covering the failure
modes.

## Evaluation

Baseline shortest-path, baseline static routing and FlowTwin compared across
multiple seeds with mean ± standard deviation, generated automatically —
**✓** `scripts/run_benchmarks.py` → `benchmarks/BENCHMARKS.md`. No number is
entered by hand.

## Demo reliability

Precomputed recordings replay through the same interface — **✓**
`scripts/record_fallback.py`, `ReplaySession`. The live path is always primary.

---

## Deliberately not built

These come from the wider master proposal rather than the P0 list in the build
brief, and were left out rather than half-built:

| Item | Why |
|---|---|
| **Safety / compression mode as a separate mode** | ◐ The compression-risk proxy itself *is* implemented — the risk score combines density, density growth, velocity drop, queue growth and opposing flow exactly as the proposal specifies, and alerts surface those causes. What is not built is a separate in-event concert scenario and a distinct "safety mode" UI. |
| **Personnel dispatch engine** | ✗ Security/medical resources, dispatch scoring and their map layer are not implemented. It is P1 in the proposal and absent from the brief's P0 list. |
| **Natural-language assistant** | ✗ P2, and explicitly excluded from the decision loop by design. |
| **Redis / PostgreSQL** | ✗ Deliberate. See `ARCHITECTURE.md` §10. |
| **Next.js frontend** | ◐ Traded for a zero-build single-page console served by the backend. Rationale in `ARCHITECTURE.md` §8. |
| **Multi-camera fusion, venue editor, city-scale transport** | ✗ P2. |

## Defects found and fixed during this audit

Recorded because they are the difference between a demo that looks right and a
model that is right.

| Defect | Symptom | Fix |
|---|---|---|
| Density averaged over a whole corridor | A queue at one gate slowed everyone in the corridor, including people 200 m back with clear space; throughput collapsed to a tenth of the real value | Density and speed evaluated per ~12 m cell |
| Links accepted people at capacity until physically full | Corridors silently absorbed impossible numbers instead of pushing congestion upstream | Backward-wave receiving function — a link stops accepting before it is full, so congestion spills back |
| Queue extent measured only at the stop line | The standing queue occupied almost no length, so people had to walk *through* a near-jammed corridor to reach it, throttling a 500/min gate to under 200/min | Queue extent measured from everyone who has actually stopped |
| Routes cut straight through grandstands | Shortest paths used seating bowls as shortcuts, deadlocking against the people trying to leave them; the Barcelona venue gridlocked with 18,000 people stranded | A route may start or end at a stand, never transit one |
| Agents U-turning in corridors | After repeated interventions a residue bounced between two nodes and never arrived | Reversing onto the corridor just walked is refused unless it is the only option |
| Intervention penalties compounded without limit | Repeated operator action permanently distorted the cost surface | Penalties are capped and relax back towards neutral each refresh |
| What-If capacity slider sent an empty override | A control that appeared to work and did nothing | The slider now retunes the scripted timeline event itself |
| Alert cards rebuilt on every frame | Entry animation restarted 5×/second, leaving the alert panel permanently mid-fade and effectively invisible | Cards keyed on structure; live values written in place |
| Orphaned sessions kept simulating | A refreshed browser tab starved the event loop and new runs appeared to hang | Sessions with no subscribers idle and are reaped |
| Model inference pinned to two threads | A 66-row inference took 1,000 ms instead of 9 ms | BLAS/OpenMP thread pools pinned at import |

## Verification performed

- `backend/tests/` — 70 tests across simulation, intelligence and API
- `scripts/ui_check.py` — drives the full acceptance path in a real browser, fails on any console error or failed request
- `scripts/run_benchmarks.py` — multi-seed quantitative evaluation
- `scripts/train_predictor.py` — held-out validation of the predictor