# Propagation Next Queue

## Landed Overnight
- Real LR-ITM backend via vendored `itmlogic`
- Coverage/heatmap routing through the propagation service
- Fast-display heatmap backend policy (`itm` solve + `lr_lite` raster)
- Heatmap backend metadata in logs, audit, and Results UI
- Dry clutter runtime scaffolding with manual/preset vegetation/structure terms
- Dormant moisture schema/hooks with preset support

## Best Next Engineering Moves

### 1. Clutter Data Feeders
Build the first real samplers:
- vegetation/clutter raster query contract
- structure raster/vector query contract
- path summary outputs rather than raw pixels only

Desired modules:
- `signalreach/propagation/clutter_sampler.py`
- `signalreach/propagation/vegetation.py`
- `signalreach/propagation/structures.py`

Status:
- contract and dry fallback modules are now in place and wired into runtime
- local GeoJSON / CSV samplers now exist for vegetation and structure layers
- next step is scaling beyond small local sources into richer raster/vector ingestion

### 2. Result Contract Expansion
Add richer per-link breakdowns to exported debug/audit artifacts:
- hard-block fraction
- vegetation/structure confidence
- moisture mode and confidence
- reason tags for terrain-limited vs clutter-limited paths

Status:
- backhaul artifacts now carry uncertainty/advisory and basic clutter loss terms
- reason tags now flow through the propagation contract and backhaul artifacts
- final-site summaries now carry lightweight reason tags for audit/validation use
- recommendation/site exports still need richer path-backed provenance where available

### 3. Confidence / Uncertainty Upgrade
Right now clutter uncertainty is only lightly folded into the link result.
Next pass should:
- combine terrain/model warning uncertainty
- combine clutter-data uncertainty
- combine moisture uncertainty
- surface a clearer planner-facing severity metric

### 4. Heatmap Performance Pass 2
Now that fast-display is working, the next performance gains should come from:
- stronger per-profile caching
- adaptive spacing for per-site overlays
- selective refinement near decision boundaries

### 5. Validation Corpus
Create a small regression set covering:
- lite vs ITM on known terrain profiles
- clutter-disabled vs clutter-enabled
- dry vs humid preset
- backhaul links and coverage heatmaps

Status:
- initial validation harness now exists in `tools/propagation_validation.py`
- operator guide lives in `docs/PROPAGATION_VALIDATION.md`
- summary now includes simple PASS / WARN / FAIL gates against `ITM_BASE`
- summary now includes selected-backhaul reason/advisory rollups
- thresholds are now configurable from the command line
- summary now includes lightweight site reason-tag rollups
- sampled local-source scenarios can now be exercised through the same harness
- next step is richer path-backed site provenance and preset threshold profiles

### 6. UI Exposure
Only after the backend semantics settle:
- expose dry clutter presets in Advanced Settings
- expose moisture preset mode in Advanced Settings
- keep real data-source configuration hidden until those sources exist

### 7. User-Side Validation Pass
Once the next backend chunk lands, the best field test will be:
- one baseline ITM run with clutter disabled
- one run with vegetation/structure presets enabled through raw mission JSON
- compare recommendation changes, backhaul edge metadata, and runtime drift

## Suggested Order
1. real clutter samplers
2. richer uncertainty/confidence synthesis
3. validation corpus thresholds / reason-tag rollups
4. UI controls
5. moisture beyond presets
