# 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-64` px
- candidate fraction guard: `<=10%`
- search distance: `6` px
- edge-connected components excluded

Stage-2 (new):

- candidate size: `65-4096` px
- candidate fraction guard: `<=5%`
- search distance: `12` px
- 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 (`<=64` px).
- 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-4096` px) 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

1. 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.
2. Leave behavior unchanged and accept spotty coverage - Rejected.
   Operational output quality remained poor for affected runs.
3. Fill all remaining interior holes without size/fraction guard - Rejected.
   Too aggressive and risks inventing large synthetic surfaces.

## Consequences

- Positive:
  - Improved `K` continuity in runs with medium interior POLARIS nodata islands.
  - Better downstream `A` coverage in off-channel hillslope areas.
  - Explicit stage provenance in manifest supports review and tuning.
- 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-channel `K` gaps 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_policy` and per-property summaries while nested `stage1`/`stage2`
  records carry the full two-stage contract.
