WEPPcloud

← Back to help

Postfire Debris Flow Implementation Roadmap

2026-09-16: Kf/report revision package implemented after ancestor 9395f4722. New M1 prepares traceable STATSGO Kf without POLARIS/RUSLE; the report evaluates a bounded curve with P50, numeric values and rainfall-origin labels. Restarted forest UI/RQ acceptance passed on nervous-mesquite and a no-RUSLE fixture, with independent raster/table checks and canonical archive/restore. Full suite passed (8,693 tests, 103 skips); all final independent reviews PASS. The package is closed. Source/runtime contract; ADR-0068. Older dated entries below describe their implementation stage and do not override this policy.

2026-09-15: fresh-basin Run preparation is wired after contract checkpoint e8c40adda. The new regression reproduced the missing acquisition before the fix. Source reuse, race rejection and retry pass 44 focused tests. Normal browser/RQ acceptance on overpriced-sprawl produced all 27,450 event probabilities with 100% valid coverage and no protected-input changes. No manual pre-acquisition. Full regression: 8,632 passed, 103 skipped; remediation closed 2026-09-15.

Status: updated 2026-09-14. Production M1 NoDb, browser upload and RQ execution are implemented. M1/M3 scientific composition, shared valid-support calculations, authoritative preparation and publication are implemented. Dashboard remains pending.

Local M3 terrain/composition and basin-derived local soil-source preparation are reviewed in the completed M3 package. Two independent grid/key fixtures exercise authoritative activation and native runtime; 14 tests pass. Live development M1/M3 browser/RQ, positive synthetic M3, builder parity and archive/browse checks pass. The package closed 2026-09-14 with final regression evidence and explicit owner acceptance of the recorded credential risk without rotation. No production deployment is claimed; current behavior remains governed by the contracts below.

Maintenance Contract

This is the living delivery tracker. specification.md and its named contracts remain the authority for scientific and runtime behavior. Recommendations below are proposals until recorded as accepted decisions there.

For each implementation increment:

  1. Resolve its blocking decisions in the specification and affected detailed contracts, including rationale and any required parameterization ADR.
  2. Create an active ExecPlan for substantial work. Complete the repository's contract-first checkpoint before covered UI/NoDb/RQ implementation: operator approval, independent reviews, and a standalone contract ancestor commit.
  3. Update this roadmap and the specification in the same change set as code. Distinguish accepted intent, implemented behavior, validated behavior, and deployment; completing one does not establish the others.
  4. Record the package, implementation revision, validation evidence, remaining limitations, and disposition of each affected loose end here. Update the active package's plan and tracker before handoff.
  5. Promote durable decisions into current contracts before package closure. Keep closed packages immutable; link them only as historical evidence.

Completed Foundations

Foundation Delivered Remaining integration
M3 terrain Owned WBT D8UpstreamRelief, production invocation, exact basin membership and enforced 10 m NED13/2022 eligibility. Contract and evidence. Calibration-preprocessing equivalence is not asserted; truncated terrain remains unavailable.
M3 soils Isolated recorded-depth SSURGO-primary/original THICK fallback, bounded source acquisition and generic authoritative preparation. Runtime contract. Source acquisition requires separate bounded authority; historical raw-cache survey vintage can remain unknown.
dNBR Local normalization/summary API, explicit encoding, project-grid alignment, partial coverage, provenance, and two public Arizona fixtures; 9b99d535c. Contract, validation. Implemented in stage 5; development browser/worker validation recorded below.

The offline soil study's complete-only outputs are not a production coverage gate. SSURGO primary and original STATSGO fallback are accepted source priority. Stage 5 adds the browser upload workflow to the local dNBR backend.

Model Selection and Task Wiring

Owner request 2026-09-11: M1/M3 UI and request wiring. The shared comparison/header, side-by-side selector, conditional prerequisites and dedicated M3 RQ task are implemented after checkpoint aa30e637e. Owner decisions fix 10 m NED13/2022 eligibility, retain automatic POLARIS/RUSLE enablement and select scalar estimates with coverage masking. SSURGO validity assessment and exact scientific integration remain explicit. Evidence is tracked in the model wiring package. Validation passed: full Python 8,468/103 skipped, frontend 872, independent reviews and live selection/task/reload/preflight checks. The scaffold pending task is superseded by actual M3 composition in the M3 scientific integration package. Common analysis support and recorded-depth soil policy were ratified at checkpoint 89d673c38. Isolated soil_policy, soil_snapshot and soil_inputs now provide recorded-depth derivation, retained source copies and prepared-local cellwise composition. Local M1 accepts opt-in common support and v2 masks/readers; new production M1/M3 now uses v2 and publishes exact validity masks while retaining legacy M1 reads. Generated soil-builder parity and live acceptance are tracked in that package. The production amendment requires read-only consumption and nonregression of existing SSURGO/STATSGO soil building. Reports remain stage 7.

Completed local predictor increment

Local M1 predictor integration is implemented and validated locally with complete authentic Wallow evidence. It composes the completed slope/SBS and dNBR backends with RUSLE Nomograph K; see accepted contract. K policy is accepted in ADR-0059. Complete synthetic and authentic T/F/S outputs and missing-input cases exist. Local Climate composition is implemented in stage 4; production publication is implemented in stage 5. Completed backend contracts are not reopened.

Local Rainfall/Results Increment

The rainfall/results package implements local M1 stage 4. Its accepted contract covers events, design comparisons, inverse thresholds and bounded local queries. R02 unavailable sparse-rank behavior is explicitly approved in ADR-0062. Backend L08/L09 decisions are resolved; browser defaults/dashboard remain future scope.

Production Upload/Run Increment

Production M1 package implements stage 5 NoDb, freshness, dNBR upload/publication, RQ and the minimal upload/run control. Reports are explicitly deferred by the owner. Review the UI contract and workflow contract. Contract checkpoints are 5c0a172ee and 595816476. Development end-to-end validation passed; installation on other hosts and the owner's real-basin acceptance test remain separate. Owner UI revisions recorded: live preflight prerequisites/NOAA availability, differenced Normalized Burn Ratio label, no image-date entry, Auto-default scale select, persistent uploaded filename and visible raster-format/datatype guidance. Auto must attempt distribution-based scale detection and publish upload details and the applied scale in a wc-control__panel-summary table. Detection criteria and fixture evidence are accepted in ADR-0063; bounded correction retry is implemented. Final evidence and reviews are recorded in the package.

Delivery Sequence

Build shared scientific components, deliver a usable M1 workflow, integrate M3, then complete the interactive dashboard. M3 soil-policy work can proceed during M1 development; M1 does not need to wait for that policy. Both models remain in scope. SI/English presentation belongs in the first user-facing increment.

Stages 1–2 are complete, in the project watershed and numerical engine package. Stage 3 slope/SBS local backend is implemented and validated, in the WBT slope/SBS package. Local stage 3 composition is complete, including authentic complete-source evidence. Local stage 4 is complete, with genuine CLI/NOAA and sparse-rank acceptance. Production stage 5 is complete with development browser/worker validation. Stage 6 is implemented, acceptance in progress. Stage 7 has an owner-authorized report contract and implementation package. The saved report is implemented after checkpoint ac4deb681; M1/NOAA and M3/CLI development browser acceptance passed without model reruns. Dashboard work remains deferred. Stage completion requires its exit evidence, not only source files. Accepted scope is the existing project watershed/outlet; nested/channel assessments are excluded from initial delivery (ADR-0055).

Stage Scope and dependencies Exit evidence
1. Assessment contract Reuse the existing project watershed and resolved outlet; document authoritative mask/grid/outlet identity and full contributing-area support. Track slope/SBS/NoData decisions for stage 3. Accepted single-watershed scope (done); canonical artifact mapping and independently checked mask/outlet evidence (done).
2. Numerical engine Implement staley2017.py for both M1 and M3. Can begin after its numerical contract is resolved, independently of spatial implementation. Complete: checked coefficients, ADR-0056, 145 focused tests, six-row generated examples, independent review and full-suite validation.
3. M1 predictors Depends on stage 1 and accepted slope/SBS/NoData rules. Aggregate slope/SBS intersection, normalized dNBR, and RUSLE Nomograph K over the project watershed; emit coverage, reasons, and input identity. Reproducible real-project predictor artifacts; correct intersection and full-domain denominators; partial and unavailable watershed checks.
4. Rainfall and results Compose stages 2–3 with Climate-owned event parquet and frequency artifacts. Define event identity, schemas, canonical units, and querying. Complete: genuine event/design/inverse bundles, ADR-0062 sparse-rank policy, bounded queries, 62 focused and 8,273 full-suite passes, independent reviews; evidence.
5. Production M1 Integrate stages 1–4 through NoDb, safe dNBR upload/publication, prerequisite checks, RQ, and a minimal Pure UI upload/run control; reports deferred. Contract checkpoint followed by upload → build → results → reload under production-equivalent identities/mounts; stale inputs, failed replacement, authorization, and SI/English equivalence verified.
6. Production M3 Resolve soil policy; compose SSURGO/fallback thickness and owned WBT relief with the shared engine and production workflow. Soil-policy preparation may precede stage 5. Explicit source contribution/coverage, unusable-both-sources cases, terrain fidelity gate, and real-project M3 results through the same publication/report path.
7. Interactive dashboard Use established result/query contracts for project watershed events, detail, design comparisons, and thresholds; maps may show the existing basin and input coverage. Event selections remain consistent; no nested catchment selector; partial/unavailable results, simulation dates, unitization, accessibility, and realistic catalog performance verified.

Recommended architecture: separate predictor preparation from rainfall evaluation so climate changes do not require terrain/soil/dNBR recomputation. Define exact invalidation edges in stage 5's contract. Benchmark stored results against evaluation on demand for the project event × model × duration catalog in stage 4. There is one assessment watershed per project.

Loose Ends and Decision Gates

IDs are stable tracking labels, not payload fields. Close a row by linking its accepted specification/ADR section and implementation evidence; retain any scientific limitation that implementation cannot resolve.

ID Decision or remaining work Resolve before Current authority / status
L01 Scope resolved: existing project watershed and existing outlet. Confirm canonical artifact mapping; no new outlet selection or nested enumeration. Stage 1 completion Accepted scope, ADR-0055; artifact audit completed.
L02 Slope algorithm, SBS class mapping, unknown pixels, soil/K coverage, and independent predictor denominators. Stage 3 implementation Slope/SBS backend and both WBT bindings validated; Horn, raw DEM, strict edges and uncertainty preservation recorded (ADR-0058). Full K coverage without additional fill is accepted in ADR-0059; partial K remains diagnostic.
L03 Coefficient verification, stable sigmoid/logit, permitted rainfall/probability inputs, zero/negative denominators, negative or unreachable thresholds. Stage 2 implementation Resolved in engine contract and ADR-0056, including review fixes for adjacent targets and inverse underflow.
L04 K calibration units, artifact provenance/freshness, full RUSLE versus K-only readiness, and M3's RUSLE prerequisite. Stages 3 and 5 RUSLE dependency. M1 K-artifact readiness and identity scale are accepted in ADR-0059; M1 production freshness is enforced in stage 5; M3 requirements remain separate.
L05 Soil material inclusion, horizon validity, incomplete components, fallback granularity/triggers, and residual missing coverage. Stage 6 implementation Accepted and implemented recorded-depth policy, ADR-0067 and runtime contract. Strict offline study is unchanged.
L06 Prepared SSURGO inventory, substituted/custom/legacy soils, STATSGO source delivery and freshness; neither source usable. Stage 6 integration Soils readiness, soil contract. No implicit soil rebuild or acquisition authority.
L07 Adopt genuine 10 m M3 requirement; detect source fidelity, validate installed WBT tool/bindings, and sample accepted relief/area at assessment outlets. Stage 6 integration Terrain contract. Calibration-preprocessing equivalence remains unproven; upsampling does not establish fidelity.
L08 Ratify 1/2/5/10-year × 15/30/60-minute matrix, CLIGEN/NOAA selector/default, sample guidance, precision, and inverse target probabilities. Stage 4 implementation Rainfall contract, ADR-0062: local source/matrix/sample policy accepted; explicit inverse targets. Stage 5 accepts Project climate by default and the fixed matrix with 50% inverse target; dashboard defaults remain stage 7 scope.
L09 Stable event IDs, source/date semantics, result/export schemas, query strategy, catalog limits, and filter defaults. Stage 4 completion Rainfall contract: local event IDs, schemas, limits and deterministic queries implemented. Dashboard filters remain stage 7 scope; fixed predictors, no recovery simulation.
L10 Upload packaging, path authorization, CSRF, resource limits, replacement, concurrent builds, atomic publication, and failed-build preservation. Stage 5 implementation Implemented under production M1 contract; development validation. dNBR backend contract plus shared transport/NoDb contracts; local backend trust assumptions do not define browser safety.
L11 Exact dependency fingerprints and invalidation for DEM/routing, Soils, SBS, K, dNBR, climate, parameters, and results. Stage 5 implementation Implemented under production M1 contract; development validation. Compatibility plan. Preserve old debris_flow.nodb; define additive schemas and stale-result presentation.
L12 Effective CONUS locale mapping, legacy us, cross-boundary footprints, and server/UI prerequisite parity. Stage 5 implementation Implemented under production M1 contract; development validation. Availability. WBT/CONUS/built Soils accepted; Western US guidance is not a second regional gate.
L13 Exact Unitizer categories, API normalization, export units, and age/area evidence-domain presentation. Stage 5 implementation Unitization, scientific context. Area warning is implemented outside inclusive 0.2–8 km² (ADR-0057), with project SI/English presentation and canonical SI exports. No age input/gate in M1; future age policy remains open.
L14 Control/feature registration, payloads, job graph, dashboard host, accessibility, and empty/partial/legacy/hostile states. Relevant stages 5–7 implementation Planned organization and shared UI/RQ contracts; M1 runtime contracts and control are implemented; dashboard/accessibility work remains stage 7 scope.

Progress Log

  • 2026-09-14: scaffolded production M3/shared-support package and active ExecPlan. Recorded owner approval of common M1/M3 support with full-basin M3 ruggedness. Reviewed manuscript and NRCS documentation; legitimate paired horizons and above-100 component totals need explicit production policy. Soil-builder preservation includes source-write checks and generated WEPP input parity. No runtime implementation, source acquisition or soil rebuild performed.

  • 2026-09-11: Predictor TIFF verification now uses the operator-selected 96 MiB cap through final recheck, independently of rainfall's 64 MiB limit. See artifact admission repair.

  • 2026-09-11: Upload/status repair admits validated internal statistics caches, prepares a self-contained DEM, tracks external mask freshness, and restores linked job IDs, failure reload, status layout and safe retry callbacks. Validation and live verification are tracked in the package; reports remain deferred.

  • 2026-09-09 UTC: owner selected a nonblocking warning outside the manuscript's inclusive 0.2–8 km² study range, for both models. Accepted in the specification and ADR-0057; use full unrounded watershed area and preserve model results. Add warning propagation in stage 4 and user-facing presentation in stage 5. The completed scalar engine has no area input and remains unchanged.

  • 2026-09-09 UTC, post-closeout owner decision: the supplied manuscript is authoritative for the study's 0.2–8 km² catchment range. Corrected the unsupported 0.02 km² lower bound in the specification and retired the source-reconciliation caveat. This updates evidence-domain guidance only; no engine parameter or area gate changes. See Published Coefficients and study context.

  • Baseline: terrain and soil evaluations and local dNBR backend are complete; remaining stages and loose ends recorded. Next work: assessment contract and numerical engine. No production implementation or deployment is claimed.

  • 2026-09-09 04:18 UTC: owner selected the existing project watershed/outlet and manual isolation of suspected burned basins. Removed the per-channel proposal from initial scope; synchronized the specification and dashboard description. First package scaffolded for stages 1–2; numerical policies remain proposed in its decision register. No executable implementation started.

  • 2026-09-09 04:33 UTC: verified publication coefficients and equations; audited existing Topanga watershed in the container (49,917 cells, outlet included, matching grids and unchanged hashes). Stage 1 mapping is now documented in the specification. Stage 2 contract is drafted in staley2017_engine.md, explicitly proposed pending N01–N04 owner resolution; engine implementation and final review remain.

  • 2026-09-09 UTC: owner approved N01–N04; implemented pure scalar engine, generated synthetic examples for six model/duration rows and passed 145 focused tests. Independent correctness review resolved adjacent-baseline cancellation and inverse underflow; no open findings. Full-suite validation and package closeout are running. L01/L03 are resolved; L02 and L04–L14 remain.

  • 2026-09-09 UTC closeout: stages 1–2 complete. Full suite passed 7,959 tests with 72 skips; final focused suite passed 145. Container fixture and synthetic example reproduction, API/stub and docs gates passed; plan archived and board moved to Done. See validation. Stage 3 starts with slope/SBS/K unit/support policy; stages 3–7 remain pending.

  • 2026-09-09 05:08 UTC: scaffolded owned WBT slope/SBS package for part of stage 3. Initial source inspection distinguishes FVSlope, Florinsky and Horn; Horn/raw DEM recommendation requires evidence and policy disposition. No nested catchments, new M1 resolution gate or runtime wiring introduced.

  • 2026-09-09 UTC: owner explicitly adopted Horn 3×3 (ADR-0058). Raw DEM, edge handling and incomplete-support behavior remain pending; comparisons now characterize the selected method rather than reselect its algorithm.

  • 2026-09-09 UTC: owner accepted uncertainty preservation for slope/SBS. Unknown intersection cells retain T bounds and unavailable point T; no partial-support extrapolation. Verified the supplied pysheds link describes routed drop/distance, not Horn; it is not calibration-parity evidence.

  • 2026-09-09 UTC: historical USGS evidence confirms ArcGIS planar/Horn-style slope in the preserved 2022-named workflow. The modern directional helper follows a 2023 migration; its predictor compatibility is a suspected regression to investigate. Original 2017 calibration method is still unconfirmed. Do not use current pfdf as M1 T oracle.

  • 2026-09-09 UTC: completed the local StaleySlopeSbs Rust backend, both bindings, 60 analytical and 24 security CLI checks, six-terrain panel and independent reviews. Validation and limitations. Stage 3 remains partial: K integration, normalized dNBR composition and production predictor preparation/orchestration are successor work. No binary installation or deployment was performed.

  • 2026-09-09 15:06 UTC: local M1 predictor package scaffolded for remaining local stage-3 composition. See the accepted contract. Covers WBT-compatible prepared inputs, independent T/F/S support and provenance. K unit verification, coverage policy and artifact-only readiness remain decision gates. Execution has not started; live publication and UI/RQ remain stage 5 work.

  • 2026-09-09 execution: owner accepted P02/P03, recorded in ADR-0059. Local adapter and 50 boundary tests implemented; actual binary generated synthetic complete and authentic strained-mod missing-dNBR bundles. Correctness findings closed. Full suite: 8,016 passed, 72 skipped; API/stub/docs gates passed. Stage 3 remains open for authentic complete source evidence. No production publication or climate integration claimed.

  • 2026-09-09 UTC: owner rebuilt Wallow using final polygon SBS. Matching June 23 dNBR and rebuilt Nomograph K yield full T/F/S support on 12,973 cells, zero unknown intersections and explicit scenario outputs. Local stage 3 acceptance is complete; area applicability warning retained. Production wiring remains stage 5 scope.

  • 2026-09-10 05:15 UTC: reviewed completed M1 contract/validation and authentic Wallow acceptance; scaffolded local rainfall/results package. Climate CSV rounding, missing-column zeros and sparse-duration rank clamping are explicit decision gates. Review is read-only, not a new correctness/security signoff.

  • 2026-09-09 Pacific execution: stage 4 local adapters/results/query implementation and genuine Wallow CLI/NOAA artifacts exist. Sparse-rank R02 approval remains pending, so stage 4 stays open. See the rainfall/results tracker for focused, full-suite and independent review evidence. Stages 5/7 remain unimplemented.

  • R02 owner approval: unsupported CLI positive ranks now retain unavailable rows with rank/count diagnostics, preserving supported scenarios and Climate CSV parity. Final validation and package closure are recorded in the tracker.

  • 2026-09-10 06:50 UTC closeout: local stage 4 complete. Explicit R02 approval, 62 focused tests, 8,273 full-suite passes (77 skips), genuine CLI/NOAA and controlled sparse/unknown-T evidence, and independent review gates passed. ExecPlan archived. Backend L08/L09 resolved; browser defaults and production publication/dashboard remain stages 5–7.

  • 2026-09-10 07:23 UTC: owner scoped production upload/run with NoDb, prerequisites/freshness, publication and RQ. Scaffolded exact simple UI labels/layout/state proposals and runtime checkpoint. Reports/dashboard deferred; completion status and protected model-file access only. No runtime implementation or deployment; UI/default approval remains pending.

  • 2026-09-10 production M1 closeout: stage 5 complete. NoDb state, live owner freshness, distribution-based dNBR upload/correction, RQ and minimal control passed actual development browser/worker acceptance. Full Python 8,312 passed/77 skipped; focused production 14 and frontend 841 passed, required reviews/gates passed. L10–L12 and M1 portions of L04/L08/L13/L14 are delivered. Reports, dashboard, M3 and the owner's real-basin acceptance remain separate. Runtime changes are uncommitted. Evidence.

  • 2026-09-11: wired the published M1 task into preflight with TaskEnum 🌋, independent of legacy debris and WEPP execution. Partial publications count as complete; timestamp invalidation is advisory and detailed artifact freshness remains authoritative. See completion contract and validation package.

  • 2026-09-11: corrected completed-output layout to publish events.parquet, design.parquet, inverse.parquet, and manifest.json directly in postfire_debris_flow/, browsable like other module outputs. Existing accepted results can be republished without rerunning the numerical engine. See the direct-output package.

  • 2026-09-11: Artifact observability replaces hidden attempts with visible attempts/, preserves failed work and per-attempt receipts, and installs canonical review/CI retention gates. addicted-reservist migrated without changing raster/table bytes; freshness, ordinary browser/downloads, and archive/restore verified. Offline M3 counting rasters are retained as inspectable support evidence. M3 production and reports remain deferred.

  • 2026-09-11: Enqueue handoff fix removes the successful post-enqueue NoDb write that raced an immediately starting upload/model worker. Exact queued receipts persist before admission; 85 focused tests and an actual retained-upload retry passed.

2026-09-17 active CLI repair

Worker admission, source preparation and publication accept only settled active CLI ctime drift verified against admission bytes. Contract checkpoint 567eacf7d; delivery evidence. Other source and artifact guards retain their existing semantics.

NFMS-01 failed migration mutation consistency

The 2026-10-30 NFMS-01 package adds the shared failed-state scope to manual migration mutation. This is bounded persistence consistency work, with no model, receipt, publication or migration-resume contract change. Real serialization failure/resume tests must assert held-reference state as well as durable bytes; manual repair of the controller in the test is not recovery evidence.