ADR-0005: RUSLE K Conservative Second-Stage Gap Fill
Status: Accepted
Date: 2026-05-27
Review Date: 2027-05-27
Context
The existing RUSLE POLARIS K preprocessing filled only small interior nodata
components (<=64 px) before near-surface aggregation. In stony Southern
California runs, this left substantial off-channel nodata islands in K and
A outputs, producing visually spotty coverage despite valid surrounding
terrain.
The existing stage-1 behavior should remain conservative and unchanged. The requested change is to add a bounded second stage that can fill medium interior holes while preserving strict safeguards against broad interpolation.
Decision
Keep the current stage-1 policy and add a second conservative fill stage.
Stage-1 (unchanged):
- candidate size:
1-64px - candidate fraction guard:
<=10% - search distance:
6px - edge-connected components excluded
Stage-2 (new):
- candidate size:
65-4096px - candidate fraction guard:
<=5% - search distance:
12px - runs only on residual nodata after stage-1
- edge-connected components excluded
Both stages keep smoothing iterations at 0 and use inverse-distance filling.
Manifest reporting is expanded so policy and outcomes are explicit for each stage while retaining stage-1 top-level keys for backward compatibility.
Decision Provenance (Required for Parameterization Changes)
Decision Venue: Codex user request thread, 2026-05-27 PDT
Participants Present: User, Codex
Decision Owner(s): User / WEPPcloud operator request
Implementer(s): Codex
Change Summary
Old behavior:
- one-stage conservative fill only (
<=64px). - medium interior gaps remained unresolved by design.
New behavior:
- two-stage conservative fill:
- stage-1 small holes (existing behavior), then
- stage-2 medium holes (
65-4096px) under stricter fraction guard.
- manifest includes nested stage policy/outcome metadata.
Rationale
- Preserves previously validated stage-1 behavior.
- Adds a controlled pathway for medium residual holes that materially affect map continuity.
- Keeps conservative controls explicit and auditable.
- Avoids introducing UI knobs or unconstrained interpolation.
Alternatives Considered
- Increase stage-1 max hole size and keep one stage - Rejected. This would blur the distinction between small and medium fill behavior and hide the contract change behind existing keys.
- Leave behavior unchanged and accept spotty coverage - Rejected. Operational output quality remained poor for affected runs.
- Fill all remaining interior holes without size/fraction guard - Rejected. Too aggressive and risks inventing large synthetic surfaces.
Consequences
- Positive:
- Improved
Kcontinuity in runs with medium interior POLARIS nodata islands. - Better downstream
Acoverage in off-channel hillslope areas. - Explicit stage provenance in manifest supports review and tuning.
- Improved
- Risks:
- Over-fill risk is reduced but not eliminated; bounded by stage-2 fraction and component-size guards.
Evidence
- Work package:
docs/work-packages/20260527_rusle_k_second_stage_gap_fill/package.md - Runtime implementation:
wepppy/nodb/mods/rusle/k_integration.py - Regression tests:
tests/nodb/mods/test_rusle_k_integration.py - Run diagnosis motivating change:
/wc1/runs/st/strained-mod/rusle/showed residual off-channelKgaps after stage-1-only fill.
Risk and Rollback Notes
- Monitor sensitivity by comparing affected runs before/after rollout.
- If stage-2 fill appears too aggressive, rollback path is to disable stage-2 and retain stage-1 behavior unchanged.
Implementation Notes
- Backward-compatible top-level stage-1 policy keys are preserved in
k.gap_fill_policyand per-property summaries while nestedstage1/stage2records carry the full two-stage contract.