Halifax reconstruction, time-margin metric, and the operator console

[legend5teve]

Two bodies of work. The Halifax reconstruction modules, which turn the domain-expert
exchange into a runnable E0 substrate, and an operator console that wraps the simulator
without modifying it and lets a scenario package be authored by drawing on a map.

Halifax reconstruction

• M1 alert engine. A timed, area-scoped alert schedule in alerts.json, resolved
  per agent and per instant, so the information regime becomes a property of where a
  household is and what has been issued.
• C.7 belief-only compliance. An authority-trust channel, with the mandatory order
  rule removed, so an order enters through belief and not as a switch.
• M2 staggered awareness. A household is dormant until a signal reaches it, and its
  urgency clock starts at that instant rather than at t=0.
• M3 door-to-door and timeline export. The RCMP sweep channel, and a consolidated
  per-run timeline covering ignition, alerts, awareness, departure, arrival, and
  clearance.
• Part J metrics. Mobilization delay, order compliance, awareness-source share, area
  clearance, corridor flow, and the non-evacuee fire-reach companion count.
• M0 clock fix. DECISION_PERIOD_S moved to 240 s against a 0.2 s integration step,
  guarded so a decision round is always a whole number of SUMO steps.

Time margin, the outcome measure that was missing

Every arm reported 182 of 182 arrived and zero fire contact, at the historical timing and
with every alert delayed an hour alike, so nothing measured the cost of being late.

Time margin reports the gap between a household leaving and the fire reaching its home.
Fire arrival is interpolated against the previous sample rather than quantised to the
240 s round, and homes the fire never reaches fall back to the closest the fire came, so
a run has a number either way. Households resolve to cleared, caught_at_home,
never_threatened, or never_departed_safe.

Building-centroid hazard basis

Hazard distance was measured to the spawn edge polyline, so every household on a street
inherited the exposure of its most exposed corner. Configs carrying home_xy building
centroids now resolve per household. Everything else keeps its spawn edge and is
bit-identical to before, and the basis travels in the metric output and the run params so
the two experiment batches can never be pooled.

Two new configs, neither replacing anything. halifax_3town_e0_centroid and
halifax_3town_e0_centroid_exact both carry the same 45 edges and 182 households as
halifax_3town_e0. The exact one is the one to run.

Snapping correctness

Building-to-edge matching measured to the nearest middle vertex, which put a house near
the end of a long street onto a different street. It now measures to the edge polyline
with the same call the hazard model uses.

Households also no longer spawn on a motorway, motorway link, trunk, or trunk link.
Passenger cars are allowed on all of them, so drivability alone was never the right test.
A building whose nearest road is one of those is matched to the nearest community street.

Runtime

Position, angle, edge, and route were each read twice per vehicle per step. They now
arrive on one TraCI subscription call per step. The per-step stdout log is off by
default, and fire polygons are drawn only under a GUI binary.

Measured on an 1800 s run, 1,750,605 TraCI calls to 109,959. A 3600 s run went from 194 s
to 102 s wall clock with a byte-identical metrics summary.

Operator console

Runs the simulation script as it is, through a launcher that attaches a read-only bridge
between TraCI steps. The bridge issues no TraCI command and changes no simulation
variable, and ui/tests/test_run_parity.py proves the trajectory is unchanged. Console
runs land in outputs/ui_runs/ so they cannot sit beside a research campaign. The
backend is standard library only, so nothing is added to the environment the simulator
runs in, and the built interface needs no network at any point.

Authoring. An operator draws a box, the buildings inside become households, a second
selection becomes the area an order covers, and fire origins are placed by click with a
scrubber showing the front at a chosen instant. A fourth tool sets one building's agent
count, since most buildings hold one vehicle while a school or a care home holds many.

Buildings are the unit of selection because that is what an operator and the record both
name, and edges are the unit the simulator inserts on, so the translation happens once
when the package is written. That resolved building-level alert areas without touching
agentevac/.

An alert area is a strict subset of the households, enforced in the selection, the view,
and the backend. A building holding no agents cannot be evacuated, and including it would
pull its road into the ordered area and order households that were never selected.

The write path creates a package directory or does nothing. A name already under
configs/ is refused with 409, a failure part way through removes what was written, and
no code path opens an existing package file for writing.

Review notes

• agentevac/simulation/main.py carries the time-margin wiring, the centroid basis, and
  the TraCI batching together, because they cannot be separated by file.
• One default changed. The per-step vehicle log is off, restored with VEHICLE_STEP_LOG=1.
• configs/westwood_uitest is a package authored during browser verification, 175
  buildings and 821 agents. Safe to delete.
• Map bundles under ui/assets/previews/ are generated and gitignored. Build them with
  python -m ui.tools.build_map_assets, about 20 s per package.

Verification

672 Python tests pass with 4 skipped, 85 frontend tests pass, typecheck clean, production
build succeeds. The parity test is opt-in behind AGENTEVAC_UI_SLOW_TESTS=1 since it
starts SUMO twice.

The authoring path was checked end to end against a live backend, and the whole interface
was walked through in a browser.

🤖 Generated with Claude Code