feat(v0.7-fire-tracker-2): movement analysis -- growth + halt detection

Phase 2 of FIRMS+WFIGS fusion. v14.sql adds fire_passes table for
per-satellite-pass centroid tracking + drift computation. FIRMS handler
now detects pass boundaries (satellite + time bucket), computes pass
centroid (median of pass pixels), Haversine drift from previous pass,
bearing to 8-way direction, mi/h speed. Drift >= 0.5 mi (configurable)
emits wildfire_growth broadcast with wire including movement vector
and nearest-town context. Halt detection: fire with no new pixels for
>=12h (configurable) emits wildfire_halted broadcast (routine). Two
new ALERT_CATEGORIES: wildfire_growth (priority), wildfire_halted
(routine). All thresholds GUI-editable via adapter_config.fires.*.
Phase 3 (spotting) and Phase 4 (LLM summaries) deferred to subsequent
commits.

Schema (v14.sql):
- fire_passes table (irwin_id FK CASCADE, pass_id, pass_centroid_lat/lon,
  pixel_count, total_frp, pass_started_at, pass_ended_at,
  drift_mi_from_prev, drift_direction, drift_mi_per_hour). PRIMARY KEY
  (irwin_id, pass_id) so the UPSERT path is cheap; secondary index on
  (irwin_id, pass_ended_at) for the prev-pass lookup + halt counter.
- fires gains last_pass_id, last_pass_at, halt_broadcast_at columns.
  halt_broadcast_at is latched per halt event; the detector filter
  (halt_broadcast_at IS NULL OR halt_broadcast_at < last_pass_at)
  reopens eligibility automatically when an idle fire receives a new
  attributed pixel that advances last_pass_at.

adapter_config (defaults.py REGISTRY):
- fires.growth_drift_threshold_mi = 0.5 (float). Per-pass centroid drift
  at or above this fires wildfire_growth. 0.5 mi matches the design
  doc Phase 2 spec and is roughly 2x the VIIRS 375m pixel size (i.e.,
  detectable as more than centroid jitter).
- fires.halt_passes_threshold = 2 (int). Documented intent; the
  operational rule uses halt_minimum_seconds below as the time gate
  because per-satellite pass-count enforcement would require modeling
  the global VIIRS schedule per satellite. The 12h gate subsumes it
  (4 passes/day in Idaho).
- fires.halt_minimum_seconds = 43200 (int, 12h).

ALERT_CATEGORIES (notifications/categories.py):
- wildfire_growth: priority/fire. FIRMS handler tags data["category"]
  + data["severity"] on the pass-boundary path when drift >= threshold.
- wildfire_halted: routine/fire. Halt detector tags data["category"]
  + data["severity"] when a fire transitions to idle for >=12h.

FIRMS handler (central/firms_handler.py):
- The Phase 1 attribution branch now passes through
  _handle_pass_boundary(): UPSERT fire_passes row for the current
  (irwin_id, pass_id) with median centroid + pixel count + total FRP
  + min/max acq_time; lookup the prior pass; compute drift mi +
  8-way direction + mi/h speed and write them into the current pass
  row (only the FIRST boundary fills these; subsequent in-pass pixels
  COALESCE keep them stable). Update fires cursor (last_pass_id,
  last_pass_at) and current_centroid_lat/lon to the latest pass
  centroid -- this overrides Phase 1's 24h all-pixels median for
  fires that have pass data.
- Growth wire emitted ONLY at the boundary (last_pass_id != current,
  prev pass exists, drift >= threshold). Subsequent in-pass pixels
  stay silent because pass_id == last_pass_id.
- _maybe_emit_halt runs as a final fallback when neither growth nor
  cluster has fired. SELECT one fire matching the halt criteria,
  stamp halt_broadcast_at, return the wire. The fallback ordering is
  growth > cluster > halt so a busy fire's growth broadcast doesn't
  starve a quiet fire's halt.
- New helpers: _bearing() (great-circle initial bearing, deg CW from N),
  _direction_8() (compass 8-way mapping with +/-22.5 deg sectors).

Wire strings:
- wildfire_growth: `🔥 <incident_name> moving <dir> <speed:.1f> mi/h
  ~<dist_to_nearest_town:.1f> mi from <nearest_town>`. nearest_town
  via meshai.central_normalizer.nearest_town (same Photon-backed
  cache that wfigs_handler uses); failure falls back to bare
  "moving <dir> <speed> mi/h".
- wildfire_halted: `🔥 <incident_name> no growth in <hours>h`.

Tests (tests/test_fire_tracker_phase2.py, 10 cases all green):
- 2-pass attribution with pass2 1.0 mi N of pass1 -> drift=1.0,
  direction='N', mi/h computed, growth wire returned, data tagged.
- Drift below threshold (0.3 mi) -> NO growth broadcast; pass row
  still records the (sub-threshold) drift for ops visibility.
- Halt detector: last_pass_at 14h ago -> fires once, halt_broadcast_at
  stamped.
- Re-run halt detector with halt latched -> NO second broadcast.
- Halt re-eligibility: halt_broadcast_at < last_pass_at -> eligible
  again (a resurrected then re-idled fire).
- Bearing + direction round-trip across all 8 cardinals.
- Direction sector boundary (22.5/67.5 deg) correctness.
- adapter_config seed for 3 new fires.* keys.
- Two new ALERT_CATEGORIES registered.
- 5-pixel single-pass aggregate (pixel_count, total_frp sum, median
  centroid, started/ended_at min/max).

Phase 1 test fix:
- tests/test_fire_tracker_phase1.py::test_centroid_recomputes_as_median_across_passes
  retimed to 12:00/12:10/12:20 so all 3 pixels land in one
  N20 bucket. Phase 2 makes current_centroid_* the per-pass median
  (latest pass overrides Phase 1's 24h median); the same-pass shape
  preserves the original median-computation intent. 39 total tests
  green across phase1/phase2/or-arch/include-roundtrip.

Live verification on CT108 after rebuild:
- v14 migration applied (schema_meta version=14, no Traceback in 3 min).
- adapter_config.fires.growth_drift_threshold_mi = 0.5
- adapter_config.fires.halt_passes_threshold = 2
- adapter_config.fires.halt_minimum_seconds = 43200
- Container healthy.

Synthetic 100-pixel probe inside prod container (PROBE-V07P2-*,
cleaned up after):
- Pass A (50 pixels @ 12:00-12:25, N20 bucket 329768): centroid
  (44.30000, -115.50000), pixel_count=50, total_frp=975.0, drift=NULL
  (first pass).
- Pass B (50 pixels @ 18:00-18:25, N20 bucket 329772, centered 1.2 mi
  NE of A): centroid (44.31230, -115.48282), pixel_count=50,
  total_frp=975.0, drift_mi_from_prev=1.1703 (~design target 1.2 mi
  with -0.03 mi rounding), drift_direction="NE",
  drift_mi_per_hour=0.209 (1.17 mi over 5.5h between pass ends).
- Growth wire: "🔥 Probe Movement Fire moving NE 0.2 mi/h, ~13.0 mi
  from Long Creek Summit Home" (Photon nearest-town anchor populated
  successfully).
- Exactly ONE growth broadcast (first pixel of pass B); 99 other
  pixels stayed silent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Johnson (via Claude) 2026-06-06 06:12:36 +00:00
commit f5c566c6c0
7 changed files with 746 additions and 16 deletions

View file

@ -277,18 +277,48 @@ REGISTRY: dict[tuple[str, str], dict[str, Any]] = {
},
# =================================================================
# FIRES -- 1 setting (default attribution radius for FIRMS -> fire matching)
# FIRES -- 4 settings (Phase 1 radius + Phase 2 growth/halt thresholds)
# =================================================================
# Per-fire override lives in the fires.spread_radius_mi column; this
# is the global default used when that column is NULL. v0.7-fire-1
# ships with 5 mi based on the design doc's open question #1
# ("Spread radius default. Start with 5 mi per fire?"). Tune from
# operations once we have a week of observed attribution rates.
# Per-fire spread radius override lives in fires.spread_radius_mi;
# the value below is the fallback. v0.7-fire-1 shipped 5 mi based on
# design doc open question #1 ("Spread radius default. Start with
# 5 mi per fire?"). Tune once we have a week of observed attribution
# rates.
("fires", "spread_radius_mi_default"): {
"default": 5.0,
"type": "float",
"description": "Default attribution radius for FIRMS hotspot -> fire matching, miles. Per-fire override in fires.spread_radius_mi.",
},
# v0.7-fire-2 -- growth + halt detection thresholds.
# growth_drift_threshold_mi: a per-pass centroid drift of at least
# this many miles fires wildfire_growth. 0.5 mi matches the design
# doc (Phase 2 spec: "Centroid drift > 0.5 mi/pass") and is roughly
# the noise floor of a single VIIRS pixel centroid (375 m ~ 0.23 mi).
("fires", "growth_drift_threshold_mi"): {
"default": 0.5,
"type": "float",
"description": "Centroid drift between consecutive satellite passes (miles) that fires the wildfire_growth broadcast.",
},
# halt_passes_threshold: number of consecutive satellite passes with
# no new pixels before the fire is considered halted. Default 2 ~
# 12h in Idaho (VIIRS gives 4 passes/day). Combined with the
# halt_minimum_seconds time gate below; both must be met.
("fires", "halt_passes_threshold"): {
"default": 2,
"type": "int",
"description": "Consecutive empty satellite passes before wildfire_halted (combined with the halt_minimum_seconds time gate).",
},
# halt_minimum_seconds: minimum wall-clock idle time before halt
# can fire. 12h handles the gap where 2 N20 + 2 N passes would have
# crossed the fire's location. We rely on this time gate as the
# operational halt rule -- pass-count enforcement would require
# tracking the global VIIRS schedule per satellite; the time gate
# subsumes that.
("fires", "halt_minimum_seconds"): {
"default": 43200,
"type": "int",
"description": "Minimum elapsed seconds since the most recent attributed pixel before wildfire_halted can fire.",
},
# =================================================================
# FIRMS -- 7 settings (storage floors + dedup + 3 v0.7 cluster knobs)