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
- Retain least-cost breach as the disturbed9002 default - rejected because it does not reproduce TOPAZ conditioning and was implicated in the observed drainage discrepancy.
- Make TOPAZ conditioning the global WBT default - rejected because the operator requested one config and other workflows have not approved output drift.
- 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.mddocs/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.