WEPPcloud

← Back to help

ADR-0032: Topaz Conditioning for disturbed9002 WBT

Status: Accepted

Date: 2026-07-30

Default update: ADR-0036 supersedes only this ADR's decision to make topaz the disturbed9002_wbt.cfg default. The topaz token, implementation, and runtime safeguards specified here remain accepted.

Context

The WBT channel pipeline currently offers generic fill, breach, and least-cost breach conditioning. Investigation of a waterbody-adjacent outlet showed that conditioning choice can materially change the local drainage direction. weppcloud-wbt now contains a source-faithful Rust translation of TOPAZ FILDEP and RELIEF with exact stage parity across seven golden cases, including irregular NoData and an NLCD-water-masked production DEM.

Decision

Add topaz as an explicit Channel Delineation conditioning value backed by WBT TopazConditionDem. Use its default maximum obstruction width of 2. Change the new-project default only in disturbed9002_wbt.cfg from breach_least_cost to topaz. Bound this native conditioning call to 540 seconds so the wrapper has 60 seconds to terminate and reap its process group before the channel child-job timeout. For an effective topaz selection, enforce a child-job minimum of 600 seconds even when RQ_ENGINE_FETCH_DEM_BUILD_CHANNELS_TIMEOUT is configured lower; higher configured values remain effective.

Decision Provenance

Decision Venue: Codex API workspace thread, 2026-07-29 18:24 PDT; exact request retained in the DOM-05A contract decision

Participants Present: requesting WEPPcloud operator; Codex

Decision Owner(s): the requesting WEPPcloud operator owns the algorithm, label, obstruction width, and config-scoped default. Codex selected the 540/600-second native/parent timeout pair as an implementation safety constraint under the accepted contract and independent release review (personal identity and external issue identifier were not exposed by the API context).

Implementer(s): Codex

Change Summary

Old behavior: new disturbed9002_wbt runs initialized fill_or_breach = "breach_least_cost".

New behavior: new disturbed9002_wbt runs initialize fill_or_breach = "topaz" and create relief.tif with TOPAZ-compatible FILDEP and RELIEF. Existing runs, other configs, and downstream flow/channel algorithms are unchanged.

Rationale

The TOPAZ-compatible method has exact empirical parity with the historical algorithm and directly addresses the conditioning discrepancy that motivated the work. Width 2 matches historical WEPPpy TOPAZ controls and is the most thoroughly validated mode.

Alternatives Considered

  1. Retain least-cost breach as the disturbed9002 default - rejected because it does not reproduce TOPAZ conditioning and was implicated in the observed drainage discrepancy.
  2. Make TOPAZ conditioning the global WBT default - rejected because the operator requested one config and other workflows have not approved output drift.
  3. Replace one legacy token - rejected because an additive value preserves backward compatibility and makes provenance explicit.

Consequences

New disturbed9002_wbt channel builds may produce different drainage, watersheds, and derived model inputs than least-cost breach. That change is intentional. Existing artifacts and persisted project selections do not change. The runtime now requires a WBT binary containing TopazConditionDem, and the integration pins max_obstruction_width=2 and a 540-second native timeout explicitly. The Topaz build-channel child receives at least 600 seconds so a lower deployment override cannot remove the cleanup margin.

Evidence

  • /workdir/weppcloud-wbt/docs/work-packages/20260729_topaz_condition_dem_parity_hardening/artifacts/validation.md
  • docs/work-packages/20260729_topaz_conditioning_wepppy_integration/artifacts/2026-07-30_contract_decision.md
  • Seven exact FILDEP/RELIEF cases totaling 5,037,306 valid case-cells.

Risk and Rollback Notes

Release must install and verify the owned WBT binary before enabling the token. Rollback is triggered by binary discovery failure, parity failure, unexpected run-scoped output, or material production delineation regression. The safe first rollback restores only disturbed9002_wbt.cfg to breach_least_cost while retaining additive topaz compatibility for existing projects. Full token/code/binary removal requires separately authorized, audited, lock/cache-safe migration and proof that no persisted topaz remains.

Implementation Notes

Do not add a silent fallback. Contract tests must cover render, request, persistence, dispatch, config initialization, legacy compatibility, and generated output from the installed binary.