# Propagation Validation

SignalReach now has enough propagation branching that "it ran once" is no
longer a sufficient check. We need a repeatable way to compare:

- `lr_lite` vs `itm`
- clutter disabled vs vegetation / structure presets enabled
- dry vs humid moisture presets
- runtime drift as the propagation stack gets richer

## Validation Runner

Use `tools/propagation_validation.py` to
run a small scenario matrix against one mission and capture:

- generated mission variants
- solver stdout / stderr for each scenario
- `audit.json`-derived summary rows
- a Markdown summary table with deltas against `ITM_BASE`

### Default Scenarios

- `LR_LITE_BASE`
- `ITM_BASE`
- `ITM_VEG`
- `ITM_STRUCT`
- `ITM_DRY_COMBO`
- `ITM_HUMID_COMBO`
- `ITM_SAMPLED_LOCAL` when local source paths are supplied

These scenarios are intentionally preset-driven. They are not meant to prove
field truth yet. They are meant to prove:

- backend routing is behaving as expected
- clutter/moisture knobs actually move the solve
- runtime cost is visible and comparable

## Typical Usage

```powershell
cd <repo-root>
.\.venv\Scripts\python.exe .\tools\propagation_validation.py --mission .\out\runs\<run_id>\mission.json
```

By default the runner disables heatmaps so the matrix focuses on recommendation
and backhaul behavior instead of raster runtime.

If you want heatmap timing included too:

```powershell
cd <repo-root>
.\.venv\Scripts\python.exe .\tools\propagation_validation.py --mission .\out\runs\<run_id>\mission.json --with-heatmap
```

If you want stricter or looser gating:

```powershell
cd <repo-root>
.\.venv\Scripts\python.exe .\tools\propagation_validation.py `
  --mission .\out\runs\<run_id>\mission.json `
  --max-coverage-drop-pct 2.0 `
  --max-runtime-drift-s 60
```

If you want to exercise local sampled clutter sources:

```powershell
cd <repo-root>
.\.venv\Scripts\python.exe .\tools\propagation_validation.py `
  --mission .\out\runs\<run_id>\mission.json `
  --scenarios ITM_BASE ITM_SAMPLED_LOCAL `
  --vegetation-source-mode geojson `
  --vegetation-source-path C:\data\veg.geojson `
  --structure-source-mode csv `
  --structure-source-path C:\data\buildings.csv
```

Output lands under:

`<repo-root>\out\casepacks\propagation_validation_v1\<timestamp>\`

## Reading The Results

Start with `summary.md`. It tells you:

- coverage delta vs `ITM_BASE`
- site-count delta vs `ITM_BASE`
- elapsed-time delta vs `ITM_BASE`
- simple `PASS` / `WARN` / `FAIL` status checks against `ITM_BASE`
- top site reason tags from the final selected deployment set
- top backhaul reason tags and advisories from the selected edge set

Then inspect the per-scenario logs if one run looks odd.

## Current Limits

- Vegetation / structure effects are still preset-driven, not data-backed.
- `ITM_SAMPLED_LOCAL` is only meaningful if you provide local source files.
- Moisture is still a conservative preset modifier, not live weather ingestion.
- Site reason tags are summary-derived, not full per-path provenance.
- Full link-level provenance still lives in logs/KML/audit artifacts.

## Next Upgrade Targets

- replace summary-derived site tags with richer path-backed site provenance
- support named mission corpora instead of one seed mission at a time
- add preset threshold profiles for quick "strict" vs "exploratory" runs
