WEPPcloud

← Back to help

ADR-0052: Staley M3 upstream terrain definition

Date: 2026-09-08

Status

Accepted engineering terrain formula by user on 2026-09-08 America/Los_Angeles. Engineering recommendation: require genuine 10 m for initial M3 support; no production enforcement is implemented.

Decision provenance

  • Decision venue: user/Codex workspace conversation, 2026-09-08, America/Los_Angeles; exact conversation time not retained.
  • Participants present: requesting user and Codex.
  • Decision owner: requesting user.
  • Implementer: Codex; registered Rust command and both Python bindings.
  • Authorized direction: owned WBT terrain tooling and empirical 10 m/30 m study. The user explicitly adopted maximum upstream raw elevation minus outlet elevation and authorized continuation. No 30 m policy was accepted.

Change summary and recommendation

There is no existing postfire M3 runtime contract to replace. Adopt a new D8 upstream quantity H = maximum upstream raw elevation minus outlet raw elevation, including the outlet. Compute A from contributing cell count and projected meter cell area, and T = H/sqrt(A). Keep supplied conditioned routing separate from the raw measurement surface. This decision defines a physical quantity; equivalence to Staley calibration remains unproven.

Rationale and alternatives

Maximum-minus-outlet is nonnegative, uses the actual assessment outlet, and can be computed in an owned linear-time traversal. Highest-source-minus-outlet can exclude internal raw maxima. Catchment maximum-minus-minimum can measure a depression above the assessment outlet. The alternatives agree on monotonic paths but disagree under conditioning. The pinned pfdf reference fails an analytical descending-chain check and cannot select between them. Do not adopt its anomalous behavior merely to match outputs.

Evidence

See terrain contract and pinned diagnostics. The manuscript and public USGS material leave the raw-elevation choice unresolved by primary evidence alone. The user explicitly selected the proposed quantity as the engineering contract after reviewing the analytical failure.

Risk and rollback

A changed terrain definition can change every probability and threshold. No production integration, model availability, live data mutation, or default resolution change is authorized by this proposal. Revisit the proposal when calibration-method evidence becomes available. The additive tool can be withdrawn without migrating existing runs; no production M3 integration or binary installation occurred. The predeclared 24-pair study supports the conservative 10 m recommendation: controlled effects reach 10.598 probability points and 12.479% inverse-threshold change. Do not infer a universal size exemption. See the resolution decision for criteria sensitivity and population limits.

The accepted terrain tool initially supports WGS84 UTM meter GeoTIFFs, requires an explicit meter-elevation declaration and includes a conservative propagated edge/NoData coverage flag. Study-only conditioning uses FillDepressions with a 0.00001 m flat increment; area averaging, 0.02/0.1/1 km2 nested selection, 90 m nearest-channel search and diagnostic F/S values are recorded in the predeclared protocol. These are implementer-selected evaluation controls, not production defaults or publication-prescribed cutoffs.