WEPPcloud

← Back to help

Postfire Debris Flow Specification

Implemented 2026-09-16 Kf and report revision

New M1 prepares NRCS-derived STATSGO fine-earth Kf under the accepted source/runtime contract, replacing POLARIS/RUSLE as its production soil input. Enabling post-fire no longer enables those modules. Legacy provenance/readers, M3 thickness and delineation are preserved. Reports include a duration-linked response curve, P50, numeric values/CSV and explicit statistical-design versus modeled/disaggregated event rainfall provenance.

Scientific rationale: ADR-0068. Independent reviews, forest restart, normal UI/RQ acceptance, protected-input checks and archive evidence are retained in the revision package. The dated amendment below supersedes earlier M1 source/dependency clauses.

Implemented baseline

2026-09-15 amendment (wired and live-validated): explicit Run M3 prepares an absent module source pointer using the existing bounded reader and locked activation; see Run preparation. Existing valid pointers are reused; preflight and state reads remain local.

Status: updated 2026-09-14. Production M1 NoDb, upload, prerequisite/freshness, RQ execution and minimal UI are implemented under the production contract. Development validation passed; deployment to other hosts is not implied. M3 production integration is implemented; the saved report is implemented as described below, while dashboard work remains deferred. The 2026-09-14 production M3/shared-support amendment records accepted analysis support and protection of existing SSURGO/STATSGO soil building; recorded-depth rules and generic prepared-local source delivery are ratified in the runtime contract. Generic source acquisition, native M3 composition and production wiring pass local independent review; fresh-basin browser/RQ acceptance passed on overpriced-sprawl on 2026-09-15.

Track delivery stages, evidence, and unresolved decisions in the living implementation roadmap. Update this specification and affected detailed contracts alongside the roadmap in each implementation change. The roadmap tracks progress; it does not ratify proposed behavior or replace the required contract-first checkpoint.

Accepted Direction and Rationale

Decision Rationale
Separate PostfireDebrisFlow NoDb module and Pure UI control Keep model inputs, execution, and results together while preserving the older debris-flow controller and saved runs.
Assess the existing project watershed at its existing user-selected outlet Reuse the completed delineation. Users should manually isolate burned basins they suspect may be at risk; nested/channel assessments are outside initial implementation.
Follow RUSLE documentation and source organization Reuse established module, numerical-helper, integration, UI, and reference-bundle conventions.
Support WBT only Reuse the owned terrain and watershed stack; no TOPAZ integration in the new module.
Require built WEPP Soils for M3; require RUSLE K for M1 M3 reuses the project Soils inventory. M1 consumes K with its own source provenance and has no independent WEPP Soils prerequisite.
Limit availability to the continental US (CONUS) locale The model is empirical and the initial integration is limited to the conterminous United States; Western US intended-use guidance remains mandatory.
Support SI and English unitization in UI and reports Follow project unit preferences while preserving the calibrated equation units and identical model results.
Implement M1 and M3, with M1 default and explicit M3 selection M1 is the publication's recommended model; M3 offers a formulation without dNBR. Do not silently switch models for missing inputs.
Depend on RUSLE preparation/UI for M1 K Reuse POLARIS Nomograph K generation, configuration, and provenance instead of a duplicate soil estimator.
Require SBS and derive moderate/high coverage directly Use spatial severity classes rather than unrelated watershed summary proxies.
Follow SBS upload conventions for dNBR, with project-grid normalization Accept differing source extents, projections, resolutions, and value scales; avoid requiring users to pre-align rasters.
Accept partial dNBR coverage when valid data overlap the watershed Retain usable observations and expose missing coverage rather than requiring complete watershed coverage.
Derive code independently from published science Preserve WEPPpy licensing without importing or translating GPL pfdf implementation or tests.

The RUSLE dependency is established for M1's K artifact. M1 requires the named K artifact and its own current provenance, not completion of the full RUSLE model. M3 requires built Soils, SBS, Climate and the eligible 10 m NED13/2022 watershed; missing usable soil data produces explicit coverage and unavailable results, not an implicit rebuild.

Scientific Model

Staley et al. (2017), equations 4-6 and Table 4, define:

x = B + R * (Ct*T + Cf*F + Cs*S)
p = 1 / (1 + exp(-x))
R_p = (log(p / (1-p)) - B) / (Ct*T + Cf*F + Cs*S)
I_p = R_p / duration_hours

R is rainfall accumulation in mm for the coefficient duration; I_p is mm/hour. p is a probability, not a percentage. The accepted numerical engine contract and ADR-0056 define scalar validation, stable arithmetic, and inverse equality/unavailability policies. RUSLE annual erosivity R is a different quantity and must not be used as Staley rainfall.

Model selection increment (2026-09-11)

The owner requested a shared M1/M3 header comparison, side-by-side model radios, M1-only dNBR/K controls and an M3-only Soils prerequisite. Accepted presentation, model-aware task transport/state compatibility and remaining integration decisions are recorded in model selection. The UI and task wiring are implemented after checkpoint aa30e637e. The subsequent approved runtime amendment implements M3 and common-valid support for both models. Full-basin M3 ruggedness is unchanged by missing soil/SBS cells. Existing v1 M1 snapshots remain readable; new production predictors use v2 and exact masks.

Predictors

Predictor M1 M3
T Fraction of contributing area both moderately/highly burned and slope >=23 degrees Maximum upstream raw elevation minus outlet elevation / square root of total upstream area
F Mean contributing-area dNBR / 1000 Fraction of contributing area moderately/highly burned
S Mean contributing-area Kf; proposed integration uses RUSLE POLARIS Nomograph estimate Mean contributing-area cumulative soil-layer thickness in inches / 100; SSURGO derivation under evaluation

Fractions are 0-1, not percentages. M1 uses a spatial intersection of slope and severity, not the product of their separate fractions. dNBR is the continuous prefire-minus-postfire NBR difference, not classified SBS, RdNBR, or an automatically updated recovery index. Preserve imagery dates, assessment timing, and raster scaling; dividing already normalized dNBR by 1000 again would be incorrect. The proposed standardized raster stores normalized NBR differences, so its catchment mean directly supplies F; see the dNBR upload contract below.

Published Coefficients

Verified against Table 4 in the local accepted manuscript; see the publication check and ADR-0056.

Model Duration (min) B Ct Cf Cs
M1 15 -3.63 0.41 0.67 0.70
M1 30 -3.61 0.26 0.39 0.50
M1 60 -3.21 0.17 0.20 0.220
M3 15 -3.71 0.32 0.33 0.47
M3 30 -3.79 0.21 0.19 0.36
M3 60 -3.46 0.14 0.10 0.18

The study used 10 m DEMs and catchments of 0.2–8 km², with observations within the first two years after fire in the western United States. These describe the evidence domain. Availability is CONUS-only as specified below; an age warning/rejection policy remains open. Source authority (owner decision, 2026-09-09 UTC): use the operator-provided accepted manuscript, printed page 12, as authoritative for this study range. Its explicit 0.2–8 km² statement supersedes the earlier unsupported 0.02–8 km² transcription; no final-journal reconciliation is required for this decision. The numerical engine consumes explicit predictors and does not enforce catchment size.

Area warning policy (owner decision, 2026-09-09 UTC): for either model, warn when the full delineated watershed area is below 0.2 km² or above 8 km². The endpoints are included in the study range and do not trigger this warning. Compare unrounded canonical area in m² against 200,000 and 8,000,000; display unit preferences and rounding must not change the warning decision. Allow assessment and preserve calculated probabilities and inverse results; area outside the range alone must not fail readiness, reject execution, or make results unavailable. Present the warning with results and reports, for example: "Watershed area is outside the study's 0.2–8 km² range. Results extrapolate beyond the reported study areas." This warns about the evidence domain without treating it as a validated physical limit. ADR-0057 records the decision. Runtime warning integration belongs to the forthcoming project assessment/results workflow; the scalar engine has no area input.

The authors recommend M1 and found 15-minute thresholds most accurate overall. M3 is an alternative formulation, not a model assigned to a particular region.

Availability and Soils Readiness

Both models require WBT and a CONUS locale. M3 also requires a completed Soils controller build with populated, readable project soil artifacts; a controller file without built data does not establish readiness. M1 requires prepared RUSLE K and its provenance, without an independent WEPP Soils prerequisite. Show model-specific missing data and reject bypassed submissions at the server. Neither model silently initiates a soil or K rebuild. See the implemented selection and readiness contract.

Interpret continental US here as the conterminous lower 48 states and DC, excluding Alaska, Hawaii, territories, and non-US projects. Resolve eligibility through the existing project-config/effective-locale authority, not labels or interface filenames. Legacy configs commonly use locales = ["us"]; determine their canonical CONUS mapping before implementation. Do not introduce locale metadata into the config registry, which explicitly does not own that authority. Exact cross-boundary footprint handling remains to be specified.

UI guidance and reports must explain: "Empirical postfire debris-flow model intended for recently burned watersheds in the Western United States. Availability elsewhere in CONUS does not establish local validation." Include the source study's first-two-years, catchment-size, and terrain-data context. Western US is intended-use guidance, not an additional hard regional gate at this stage.

M1 also requires the RUSLE Nomograph K artifact and continuous dNBR. M3 requires a valid thickness derivation; a successful WEPP soil build alone does not prove that historical/custom/fallback runs contain suitable raw SSURGO horizons.

M3 Soil Thickness: SSURGO Feasibility

Finding (2026-09-08): SSURGO can supply a comparable cumulative profile-thickness estimate using raw component/horizon records already cached by current Soils builds. It is a substitute source requiring comparison with the original STATSGO predictor, not demonstrated calibration parity. See the detailed SSURGO feasibility assessment.

The M3 soil work package scopes source inventory, reproducible offline derivation, and a fixed-10 m comparison against original STATSGO THICK. The user requested this follow-up after terrain completion; it resolves soil-source suitability independently of terrain resolution. The subsequent owner decision selects SSURGO as primary and original STATSGO THICK as fallback. Prefer the more detailed SSURGO soil information where usable and retain STATSGO for broader coverage. Differences from STATSGO do not establish that SSURGO is less accurate.

Source priority and runtime integration are implemented. Fallback is explicit in output provenance and coverage reporting. Accepted ADR-0067 fixes cellwise fallback, recorded-depth usability and weighted incomplete-component handling. A nonmissing STATSGO pixel is not proof of complete underlying component observations; validate its NoData/nonphysical values too. Do not apply the offline 100% support criterion as an approved production gate. No live soil rebuild is authorized by this source-priority decision.

The original STATSGO THICK is cumulative layer thickness in inches, not centimeters, depth to bedrock, or WEPP's modeled profile depth. Thus:

thickness_in = thickness_cm / 2.54
S = catchment_mean(thickness_in) / 100
  = catchment_mean(thickness_cm) / 254

Use raw horizon top/bottom depths in cm to derive component thickness after validating interval topology and soil-versus-bedrock classification. Component percentage weighting followed by contributing-area weighting is the proposed map-unit/catchment method. The exact duplicate, overlap, gap, bedrock, incomplete component, and coverage rules need ratification and a parameterization ADR.

Do not reuse generated .sol depth or SurgoSpatializer's current SolThk: the former can be clipped/adjusted, and the latter sums cumulative bottom depths rather than layer thicknesses. Do not substitute a POLARIS depth interval or numeric zero for missing thickness. Missing/invalid source data must remain explicit; partial-coverage acceptance thresholds are not yet approved.

Offline M3 Soil Evaluation Contract

The version 1 offline soil contract and ADR-0053 define the study helper before executable implementation. This contract applies only to offline raw-record derivation and diagnostics. No live Soils build, NoDb/UI/RQ integration or partial-coverage availability threshold is established by the offline contract. The owner has separately approved the SSURGO-primary/STATSGO-fallback direction above. Strict soil and all-recorded-layer sensitivities remain scientifically distinct.

RUSLE and POLARIS Dependency

Current RUSLE behavior is documented in its specification. Its UI can build polaris_nomograph, polaris_epic, or both and select a default K for RUSLE soil loss. Our agreed starting input for M1 is Nomograph; EPIC is not automatically enabled for Staley by its availability in RUSLE.

  • Named input: rusle/k_polaris_nomograph.tif.
  • Standard RUSLE builds do not create the lower-level helper's rusle/k.tif alias.
  • K inputs use POLARIS mean layers over 0-15 cm, with 5:10 thickness weights.
  • Nomograph infers structure/permeability and very fine sand; optional profile coarse fragments can modify permeability. This is an estimate, not a direct STATSGO Kf extraction or WEPP Ki/Kr substitution.
  • Record source mode, depth treatment, fragment adjustment, units, gap filling, and artifact identity. The verified Nomograph scale maps to S with multiplier 1 (ADR-0059); full finite [0,1] K support and provenance are required by the implemented v1 point S. New production aggregation uses the common support accepted in ADR-0066 and implemented in v2; v1 partial K remains diagnostic. No additional gap filling is introduced. Named K readiness is independent of unrelated RUSLE factors and has no independent completed WEPP Soils prerequisite. See local contract.
  • Changing K invalidates M1 results under the implemented production freshness contract.

Terrain, SBS, and Assessment Scope

Use real contributing catchments for aggregation. The existing WBT-side Watershed._compute_ruggedness_from_dem uses DEM rectangle statistics/area; it is not sufficient evidence of a Staley-compatible catchment calculation.

For M3, pfdf evaluates relief / sqrt(area) in consistent length units, which is dimensionless. The local manuscript's section 5.2 prose omits the square root; pfdf documentation also alternates between nearest and highest ridge and incorrectly labels units in one method docstring. The user resolved the engineering definition below, and the owned WBT implementation was verified against analytical fixtures and full catchment counts/extrema. See M3 terrain evaluation for the accepted contract, implementation limitations and resolution findings.

Accepted direction (2026-09-08): implement the terrain tooling in weppcloud-wbt, then evaluate matched 10 m/30 m catchments to determine M3 resolution requirements. This keeps raster traversal in the owned Rust backend and makes resolution acceptance evidence-based. Execution is scoped in the terrain work package; the accepted formula and measured resolution recommendation are recorded below.

Discovery finding (2026-09-09): pinned pfdf 3.0.2/pysheds 0.4 returns 25 m where a descending synthetic catchment has 30 m relief under all candidate physical definitions. Raw-elevation alternatives also disagree with each other under conditioned routing. The reference therefore cannot ratify the formula; see diagnostic evidence and ADR-0052. The user subsequently adopted maximum upstream raw elevation minus outlet elevation as the engineering contract. Include the outlet in the upstream maximum and in area; use raw meter elevations with supplied conditioned D8 routing, A in m2, and T=H/sqrt(A). This choice includes internal raw maxima and measures relief relative to the actual assessment outlet. Highest-source and catchment-max-minus-min alternatives are rejected for these reasons. Calibration-preprocessing equivalence remains unproven; 30 m acceptance still requires the resolution study. ADR-0052 records decision provenance.

The completed terrain evaluation recommends requiring genuine 10 m for initial M3 support. Across 24 outlet pairs, controlled 30 m effects reached 10.598 probability percentage points and 12.479% inverse-threshold change, exceeding the predeclared 5-point/10% engineering screen. Larger sampled catchments agreed closely, but the panel does not justify a universal 30 m size exemption. See resolution findings. This recommendation is not implemented UI/server enforcement and does not establish predictive validity or CONUS-wide calibration. For illustration below the study's minimum area, a hypothetical 0.02 km² catchment has approximately 200 and 22 cells respectively. Upsampling a 30 m DEM does not establish 10 m terrain fidelity.

Project Watershed Assessment Scope

Accepted owner decision (2026-09-09 UTC): assess the watershed already delineated by the project, using its existing user-selected outlet as resolved by the canonical WBT workflow. One project supplies one assessment domain per model. Do not require a second delineation, additional outlet selection, automated burned-basin extraction, or per-channel/nested catchment enumeration. Use the full delineated upstream area, including channels and unburned portions; do not clip the assessment to the fire perimeter, valid dNBR footprint, or individual WEPP hillslopes. Confirm the canonical mask/grid and resolved outlet cell in the implementation contract rather than silently snapping a new outlet.

User guidance in the control and reports: manually isolate a burned basin that you suspect may be at risk for debris flows when creating the project. Place the project outlet to delineate that basin. This basin-selection guidance does not establish predictive validity or replace the study's area, age, and regional context. The result is a basin assessment for the selected rainfall scenario, not an aggregate probability of a debris flow occurring anywhere in a larger landscape and not a runout prediction.

ADR-0055 records why the earlier per-channel proposal was rejected for initial delivery. Nested assessments would require a separately approved scope change. Existing offline helpers and evaluation fixtures may retain multiple masks/outlets for testing; that capability is not a production workflow requirement.

The owner requested slope/SBS intersection tooling in weppcloud-wbt. The slope/SBS backend contract and implementation package cover algorithm selection, raw-versus-conditioned terrain, class mapping, coverage and owned Rust tooling. The owner adopted Horn 3×3 surface slope in ADR-0058. Execution selects raw project elevation with strict nine-valid-cell neighborhoods; original Staley slope preprocessing equivalence is not established. Historical source evidence now confirms ArcGIS planar/Horn-style slope in the preserved 2022-named USGS M1 workflow, followed by a 2023 migration to pysheds. The inspected modern helper uses directional slope: treat that as a suspected predictor-preprocessing regression, not a calibration reference. Exact 2017 tooling and predictive impact remain unconfirmed. Existing D8 flow-vector slope and WBT's projected Florinsky 5×5 Slope are separate algorithms, not approved substitutes by their availability alone. The raw tool retains coverage, full-watershed T bounds and no point T when intersection cells remain unknown. New production composition will aggregate over the accepted common valid support (ADR-0066 and production M3/shared support); it must preserve these raw diagnostics. That numerical amendment is not yet implemented. The additive StaleySlopeSbs backend and both bindings are implemented and validated locally; production M1 preparation/publication is implemented under the production contract.

The local backend contract fixes slope, explicit SBS class mapping and whole-watershed support. Any future resampling/preparation workflow requires its own integration contract. Missing SBS pixels must not silently become unburned observations.

Canonical artifact mapping (verified 2026-09-09 UTC): Watershed.bound supplies dem/wbt/bound.tif, produced by WBT from the existing D8 pointer and resolved dem/wbt/outlet.geojson. Use its valid positive routed cells, including channel cells, as the full assessment support. Validate that the resolved outlet is in that support and matches its recorded row/column and projected cell center. Do not use requested outlet coordinates to select a different cell.

Reuse the raw project DEM (Watershed.dem_fn) grid exactly: CRS, affine transform, shape and extent. Resolve D8 pointer format through the existing WBT property (flovec.tif or flovec.vrt). On a projected meter grid, cell area is the absolute affine determinant in m²; full area is cell count times cell area. Require explicit unit handling for other grids rather than assuming square meters. M3 elevation remains raw DEM elevation, not conditioned WBT relief.

The derived bound.geojson and bound.WGS.geojson are display views; user-drawn boundaries and outlet-selection masks are not the routed domain. Outlet JSON outlet_in_mask and watershed_cell_count describe an optional selection mask and must not replace direct checks of the completed routed mask. Grid disagreement, an outlet outside support, or boundary-touch diagnostics must be reported without implicit re-snapping or re-delineation. The existing WBT boundary policy remains authoritative; this audit adds no rejection cutoff.

The read-only fixture audit checks grid identity, 49,917 routed cells, outlet inclusion, polygon agreement and source hashes. This mapping establishes reuse; slope/SBS/K aggregation and scientific missing-data policies remain stage 3 work.

Local M1 Predictor Composition

The local integration.build_m1_predictors adapter composes prepared sources with the actual owned WBT executable. The accepted contract and ADR-0059 define lossless copies, independent T/F/S support, K units/coverage, provenance and retained incomplete failures. evaluate_m1_scenarios evaluates explicit accumulations through the scalar engine; no climate defaults are added.

The work package retains complete synthetic and authentic rebuilt Wallow T/F/S evidence, plus missing-input cases. Stage 3 local composition acceptance is satisfied. That local package excludes live publication; stages 4–5 now add Climate composition and production NoDb/UI/RQ without rebuilding upstream sources.

Unitization Contract

Use the existing wepppy/nodb/unitizer.py and WEPPcloud unitizer helpers for project-selected SI/English presentation in controls, tables, reports, legends, and tooltips. Any dimensional input exposed by the control must carry its unit and normalize once at the API boundary. Initial M1 exposes no dimensional model input; its upload cell size and area warning use Unitizer. Exact payloads are defined in the production contract.

Quantity SI presentation English presentation Calculation requirement
Rainfall accumulation/threshold mm in Normalize to mm before evaluation
Rainfall intensity/threshold mm/hour in/hour Normalize to mm/hour; convert to accumulation using duration
Soil thickness metric depth through Unitizer corresponding English depth Explicit cm-to-inch conversion for M3 S; do not use a display-rounded value
Relief/elevation m ft Use consistent length units with catchment area for ruggedness
Catchment area ha or km2 via existing preference acres via existing preference Canonical area in m2 for ruggedness/aggregation
Probability and burned fraction probability or labeled percent same Dimensionless; distinguish 0-1 from 0-100
Duration, slope angle, dNBR, scaled predictors min, degrees, or labeled dimensionless values same No arbitrary SI/English conversion

Reuse Unitizer's existing mm, in, mm/hour, and in/hour categories. Resolve the soil-depth display category without inventing an unimplemented unit key. M1 K remains in its calibrated source convention; any separately displayed K conversion needs an explicit unit contract, not a preference-driven change to the regression input.

Changing display units must not rerun the model, change probabilities, or rewrite canonical scientific values. Persist input/source units and scaling provenance; machine-readable exports must identify their units independently of browser preferences. Event/design/inverse export schemas are defined in the rainfall contract.

dNBR Upload and Processing Contract

Accepted direction: reuse SBS upload conventions, accept different source grids and extents, create a standardized project-aligned raster, require valid overlap with the watershed, and support partial coverage. The detailed dNBR backend contract fixes the Python normalization and summary interface; ADR-0054 records its numerical choices. Browser upload and NoDb/RQ publication are implemented in the production workflow.

The SBS precedent accepts .tif, .tiff, .img, and .vrt with a 100 MiB file cap. Its categorical value checks (integer values and at most 256 classes) do not apply to continuous dNBR. Backend v1 accepts real integer and floating- point single-band inputs, self-contained GTiff/HFA and explicitly allowlisted identity VRT wrappers. It does not execute arbitrary VRTs or read sidecars. The backend defines raster validation and resource limits; production transport adds streamed packaging, authorization and candidate publication checks.

Normalize to the authoritative WBT project grid: CRS, resolution, origin, affine transform, dimensions, and extent must match, not just the EPSG code and nominal cell size. Output is a single-band Float32 GeoTIFF containing normalized prefire-minus-postfire NBR difference with NaN NoData. Backend v1 uses compiled GDAL nearest sampling to retain source observations and holes. Use a separate coverage/support mask when needed to keep resampling from turning absent source coverage into observations. Preserve the source artifact and normalization provenance.

Treat value encoding separately from spatial scale. Explicit source scale and offset (or a resolved encoding preset) determine normalized dNBR. The local normalizer requires explicit encoding; production Auto resolves it from the valid-value distribution under the evaluated detection contract below. Preserve valid negative and zero values. NoData is not unburned and is not dNBR zero.

Production upload uses an Auto-default scale select with standard presets and a Custom factor/offset option. The adapter must resolve Auto to explicit encoding before normalization; unresolved scale cannot publish an accepted map. See the production UI contract for distribution-based detection, the uploaded-map summary table and correction flow. Distribution-v1 numerical criteria and initial evidence are recorded in ADR-0063. The local normalizer's explicit encoding API remains unchanged.

Require positive valid-data overlap with the actual watershed mask; bounding-box intersection alone is insufficient. Partial coverage is accepted and reported. For catchments with some valid dNBR, F is the area-weighted target-cell mean over observed support, with observed area/fraction reported against the full catchment. This is a partial-coverage estimate of the publication's full-area predictor in the existing local normalizer. New production M1 uses the common slope/SBS/dNBR/K support accepted in ADR-0066; upload summaries still describe the uploaded map's own coverage. Do not confuse upload support with model support. Catchments without valid dNBR have unavailable M1 results, not zero probability and not an implicit M3 result. A catchment-level gap must not discard other catchments that can be assessed.

Do not impose a new minimum coverage percentage as an unapproved heuristic. Warn on partial coverage without treating every partial upload as an error. Distinguish successful upload, successful normalization, and scientific result availability. If source overlap disappears on the target grid, normalization must return a clear unusable-at-project-resolution result rather than claim readiness or extrapolate values.

Interactive report status

The post-fire debris-flow report contract documents the owner-authorized stage-7 presentation: familiar Pure report shell, saved rainfall scenarios, existing 50% thresholds and paginated storm events. Implementation and saved M1/M3 development browser evidence are in the successor package, following reviewed ancestor ac4deb681. No production deployment is implied. The design work package retains reviews and the implementation handoff, not durable scientific authority.

Accepted production attempt identity and the validated rainfall/result bundle own displayed model, source, dates, values and provenance; current form preferences must not relabel an older accepted result. Existing rainfall/results and production contracts remain authoritative. No new calculations, source acquisition, artifact schemas, coverage cutoffs or model execution are authorized by this design work.

Rainfall Sources and Scenario Outputs

Local stage-4 implementation and evidence are in the rainfall/results package. The accepted adapter/result contract composes M1 bundles with existing Climate artifacts. Callers explicitly select source, durations, intervals and inverse targets. ADR-0062 records approved sample handling. Production stage 5 consumes these artifacts and adds completion notifications to Climate export; climate generation semantics are unchanged.

Accepted direction: focus on short return intervals and reuse Climate-owned event intensities and NOAA PDS artifacts. Do not reconstruct CLIGEN storm intensities inside this module.

The existing ClimateArtifactExportService writes climate/wepp_cli.parquet with peak_intensity_15, peak_intensity_30, and peak_intensity_60 in mm/hour. Its post-build export also produces climate/wepp_cli_pds_mean_metric.csv, using ranked wet-event intensities and the existing Weibull PDS method. It supports 1, 2, 5, and 10 years (and longer intervals), limited to intervals no greater than the number of represented wet-event years. These are project CLI-derived estimates; preserve the actual climate mode and provenance even when the selector is labeled CLIGEN.

Producer lineage, atomic event-Parquet publication and legacy new-execution readiness follow the Climate Parquet contract; embedded metadata adds no columns or intensity changes.

The Climate-owned NOAA artifact is atlas14_intensity_pds_mean_metric.csv under Climate.cli_dir. Current download eligibility checks for 2015 or legacy in cligen_db; availability is not guaranteed for every climate build. Both artifact exports can fail without failing the climate build, so readiness must validate data rather than assume files exist. The CLI frequency CSV can contain zero placeholders for missing intensity columns; these must not become design-storm inputs. Validate against the event parquet and report missing scenarios explicitly.

Implementation review also found that CLI frequency selection clamps a requested rank to the last positive observation if a duration has too few samples. The shared rank helper assigns indices across the supplied recurrence set, so exact Climate parity requires its full request context before selecting a subset. Approved R02 returns unavailable / insufficient_positive_samples when the requested zero-based rank is at least the positive duration sample count. Retain rank/count diagnostics and null rainfall/probability, while supported ranks and other durations continue. The unchanged Climate CSV clamp remains parity evidence only; see ADR-0062 for the decision and rationale.

Accepted local workflow; browser presentation defaults remain proposals:

  • Require explicit CLI / NOAA frequency source selection, using the existing project artifacts and Climate-owned frequency method. Never silently switch sources. Keep event intensities in parquet as the source of full-precision CLI values; the current frequency CSV rounds to two decimal places.
  • Evaluate 1-, 2-, 5-, and 10-year intervals for each of 15, 30, and 60 minutes: 12 scenarios for the project watershed, selected model, and source. Lead the report with 15-minute results; retain the other durations for comparison. The paper supplies duration-specific coefficients, not a prescribed return-period set.
  • Convert intensity to accumulation as R_mm = I_mm_per_hour * minutes / 60. Each scenario reports conditional debris-flow occurrence probability, its rainfall intensity and accumulation, duration, return interval, source, and predictor coverage. Different durations are separate scenarios; do not average their probabilities or interpret them as independent joint events.
  • Initial M1 supplies inverse rainfall thresholds at 50% for all three durations. A future dashboard may expose additional explicit targets under its contract. These thresholds depend on catchment predictors and coefficients, not on a rainfall-frequency source; assigning a return interval to a threshold is a separate operation.

Staley outputs occurrence likelihood and rainfall thresholds. It does not estimate volume, runout, damage, or annual debris-flow probability. Keep PDS average recurrence interval terminology; do not label a 1-year PDS scenario as 100% annual probability. Record climate record length and frequency method; merely having ten years permits the existing estimator's 10-year output but does not establish estimate precision. Missing intervals remain unavailable. The scalar engine numerical policies are accepted in ADR-0056. Sample adequacy is recorded with unavailable sparse ranks (ADR-0062). Initial production M1 uses the fixed matrix and 50% inverse target (ADR-0063).

Interactive Event Dashboard

Accepted direction: users can browse individual storm-event debris-flow probabilities and select events for more detail. Interpret events as wet-event records in the project CLI parquet. The proposed return-interval matrix is a separate design-storm comparison, not the complete dashboard event catalog. This preserves actual event combinations of duration-specific intensities instead of replacing every event with a frequency estimate.

For each event, evaluate the available 15-, 30-, and 60-minute peak intensities with their matching Staley coefficients for the project watershed and selected model. Retain event identity, climate year/date, climate mode, and source provenance. Synthetic climate dates must be identified as simulation dates. NOAA PDS supplies design-storm estimates, not a dated event catalog; switching frequency sources must not relabel project CLI events as NOAA observations.

Proposed interaction, pending detailed UI contract:

  • A linked event plot and sortable table show probabilities for the project watershed, selected model, and duration. Start with 15 minutes and allow 30/60-minute comparisons. Keep the existing project boundary/outlet visible where a map is presented; there is no catchment selector in initial scope.
  • Selecting an event updates the watershed result and event detail. A map may show the basin result and input coverage; it must not imply independently evaluated channel, hillslope, or pixel probabilities.
  • Event detail shows storm depth/duration when available, all three peak intensities and corresponding probabilities, source/date, model, watershed predictors, and data coverage/unavailable reasons. Apply project SI/English display preferences. A hyetograph requires a separate explicit reconstruction contract; peak-intensity columns alone do not supply one.
  • Keep design-storm comparisons and inverse probability thresholds accessible alongside the event view. Event frequency estimates, if displayed, are duration-specific and must use the documented frequency method.

Evaluate these events against the selected current postfire predictor state. A multidecade synthetic climate catalog is a set of rainfall scenarios under that state, not a simulation of decades of postfire recovery or a cumulative debris-flow forecast. Do not combine duration probabilities into a joint score. Event identifiers, persistence/query strategy, filtering defaults, dashboard host, and large-catalog performance requirements remain open.

Production M1 Workflow Increment

Owner scope (2026-09-10 UTC): NoDb state, prerequisite/freshness checks, dNBR upload and publication, RQ execution and a minimal control for uploading and running M1. Reports and interactive dashboard are deferred. The owner plans a 10 m project for testing; this does not change M1 resolution eligibility.

Production workflow contract and UI contract specify intended state/publication behavior, a compact required-data list, dNBR upload and one run action. Use familiar land-manager/hydrologist terminology; keep implementation details in the job log and avoid additional parameter panels. Owner revisions: required-data readiness updates through preflight in realtime; label the raster “differenced Normalized Burn Ratio (dNBR)”; omit image-date entry; offer Auto scale selection; persist the uploaded filename and show accepted raster formats/datatypes; disable NOAA when unavailable. These remove unnecessary map-preparation friction and avoid calling dNBR a soil burn severity map. The accepted UI/default/state contract precedes runtime edits in ancestors 5c0a172ee and 595816476. The production M1 package implements the accepted workflow. Initial completion means status and protected model-file access, not report tables/charts or dashboard implementation.

Planned File Organization

The scalar staley2017.py engine is implemented under its accepted contract. The M1 facade, production adapter, routes, workers and control are implemented; reports remain reserved for the deferred increment.

Location Responsibility
postfire_debris_flow.py, __init__.py in this directory NoDb facade and exports
staley2017.py Independent numerical M1/M3 evaluator
integration.py Artifact validation, catchment aggregation, orchestration
production.py, encoding.py Owner freshness, safe publication, Auto-scale resolution
results.py, rainfall_io.py Result manifests, event/design/inverse artifacts and provenance
wepppy/rq/postfire_debris_flow_rq.py Upload and model workers
wepppy/weppcloud/controllers_js/postfire_debris_flow.js Pure UI controller
wepppy/weppcloud/templates/controls/postfire_debris_flow_pure.htm Control and prerequisite presentation
wepppy/weppcloud/templates/controls/postfire_debris_flow_reports.htm Deferred report increment; excluded from initial production upload/run package
wepppy/microservices/rq_engine/postfire_debris_flow_routes.py RQ-engine submission boundary
tests/nodb/mods/test_postfire_debris_flow_*.py Numerical and integration tests
tests/microservices/test_rq_engine_postfire_debris_flow.py Route contracts
wepppy/weppcloud/controllers_js/__tests__/postfire_debris_flow.test.js UI state and payload tests

Open Decisions Before Implementation

  1. Ratify SSURGO thickness aggregation, bedrock/interval rules, missing-data coverage policy, and comparison against STATSGO THICK. Original units are resolved as inches. SSURGO primary and STATSGO fallback are approved; fallback granularity, triggers, and provenance require an implementation contract.
  2. Production application of the accepted maximum-minus-outlet terrain contract and recommended 10 m requirement; original calibration preprocessing equivalence remains unproven.
  3. M3 prerequisites, production soil/terrain freshness and publication through the shared workflow. M1 K-only readiness and freshness are implemented.
  4. Interactive event dashboard, report placement, filters and presentation of unavailable scenarios. Existing event IDs, SI export schemas, the M1 source selector and fixed scenario matrix are implemented; no new scientific defaults are implied by future dashboard work.
  5. Any future post-fire age policy, dimensional input fields and M3/report Unitizer mappings. M1 has no image-date input or age gate. Canonical continental-US eligibility, WBT enforcement, upload scaling/alignment, minimal control units and study-area warnings are implemented.

Compatibility and Validation Plan

Offline soil artifacts follow the dedicated contract above. Production M1 is additive; future M3 integration must also preserve existing debris_flow.nodb state and older outputs, and avoid renaming user-visible fields without explicit approval. Before data mutations, specify new NoDb/CSV/parquet schemas and downstream generated-artifact propagation.

Create an active implementation ExecPlan and complete the repository's contract-first checkpoint before editing runtime files. Include shared NoDb, RQ response, CSRF, controller, and feature-registry contracts. Record accepted parameterization in an ADR.

Validation should cover independently derived numerical examples, forward/inverse consistency, spatial intersection and catchment aggregation, units, missing and stale dependencies, valid/empty/legacy/hostile states, and real generated outputs. Verify absent/empty/populated/custom/legacy Soils states, server enforcement of CONUS/WBT eligibility, and SI/English input equivalence and report switching. Thickness checks must include cumulative-depth overcounting, duplicate horizons, bedrock intervals, and the 2.54 conversion; display rounding must not affect S. dNBR checks must cover alternative encodings/grids, partial watershed coverage, NoData-only overlap, valid zero/negative values, empty subcatchments, and safe upload replacement. Detailed cases live in the dNBR upload design. Compare independently authored fixtures against separately executed pfdf where useful; do not copy its tests. Terrain work needs parity and performance evidence against the owned stack. UI/RQ/NoDb boundaries require real workflow evidence under production-equivalent identities and mounts before shipping.

References

  • Staley, D.M., Negri, J.A., Kean, J.W., Laber, J.L., Tillery, A.C., and Youberg, A.M. (2017). Prediction of spatially explicit rainfall intensity-duration thresholds for post-fire debris-flow generation in the western United States. Geomorphology 278, 149-162. DOI.
  • Reference bundle and retrieval evidence.
  • pfdf model guide: implementation comparison only, not a replacement for the published method.

Local rainfall/results execution status

The local rainfall contract now defines additive event/design/inverse tables and bounded local queries. Genuine Wallow snapshots exercise both explicit frequency sources with fixed predictors. The separate production M1 contract now supplies publication; a dashboard remains deferred. The owner explicitly approved R02: unsupported positive ranks retain unavailable rows. Parameterization and rationale are recorded in ADR-0062; the package tracker records final validation.

Artifact observability

Artifact observability is mandatory. Sources, intermediate maps, diagnostic files and failed/completed attempts use visible attempts// directories and durable status receipts. Latest result files remain directly under postfire_debris_flow/. Preserve them through canonical project archive/restore. Storage migration and failure retention are governed by production M1.

Scientific integration amendment — 2026-09-14

Accepted production runtime integration and ADR-0067 govern implemented M1/M3 common-support execution, explicit recorded-depth soil policy and additive coverage artifacts. Development M1/M3 RQ/browser validation passes. Actual composition supersedes the pending-integration task; offline v1 outputs and scalar coefficients retain their established semantics.

Implementation increment after checkpoint 89d673c38: isolated recorded-depth derivation and prepared-local soil composition are implemented with retained SQLite/MUKEY/evidence copies and real SQLite/WBT tests. M1 common support is available through the explicit local support_policy='common_valid_v1' option; the local default remains offline v1. Production explicitly selects v2 for both models. Independent generated SSURGO/STATSGO/WEPP input parity, native runtime, real RQ/browser execution and archive/restore evidence are recorded in the M3 package. Its final security disposition is separate from scientific conformance.

Kf source amendment — 2026-09-16

Status: accepted 2026-09-16 after two independent reviews; implementation conformance verified on forest, 2026-09-16. The Kf source/runtime contract is the controlling amendment for new production M1.

New production M1 replaces POLARIS/RUSLE K with module-owned Kf; M3 remains unchanged. Earlier conflicting requirements remain the historical/legacy contract only once this checkpoint is accepted; do not reinterpret old accepted artifacts.

Active CLI identity amendment — 2026-09-17

The shared active-worker amendment governs M1/M3 admission, source preparation and publication. WEPP link creation or removal may change only CLI ctime without invalidating identical admitted bytes; uncached coherent verification and all other identity checks remain required. Contract checkpoint: 567eacf7d.

Failed migration mutation consistency

The manual migration boundary participates in shared NoDb failed-state recovery. See production M1 failed migration mutation state. Recovery preserves committed metadata and existing explicit migration resume; it never treats a later exception as permission to reverse published files.