WEPPcloud

← Back to help

Geneva NoDb Mod Specification

Status: Implemented Baseline (WP-00..WP-10 complete; WP-11 follow-on backlog; WP-12 storm-shape control complete) Last Updated: 2026-04-29 Owner: WEPPpy NoDb hydrology stack
Scope: Event runoff hydrograph modeling for BAER-style post-fire workflows using RMRS-GTR-334-aligned Curve Number (CN) plus unit hydrograph methods.

Name note: geneva is the project codename selected in memory of Richard H. Hawkins (passed January 2026).

1. Purpose

Geneva provides a run-scoped NoDb workflow for event rainfall-runoff analysis with:

  • raster-derived HRUs,
  • CN rainfall excess,
  • hydrograph generation,
  • batch execution over a frequency panel,
  • query/report payloads for interactive storm exploration,
  • auditable run artifacts under <run>/geneva/.

This document now records the current shipped behavior. Historical design intent is retained in deferred sections for future implementation work.

2. Implementation Snapshot (2026-04-28)

Area Current State Notes
NoDb facade + collaborators Implemented wepppy/nodb/mods/geneva/
Rust kernel entrypoints Implemented geneva_prepare_hrus, geneva_build_frequency_panel, geneva_run_batch
geneva_validate_uh Stub Exposed but scaffold-only response
WBT-only guardrail Implemented Hard fail with unsupported_backend
US-only guardrail Implemented Broad US envelope + NLCD/SSURGO compatibility checks
Run-scoped CN-table lifecycle Implemented Init/reset/modify/audit with optimistic concurrency
CN-table consumption in HRU CN assignment Implemented prepare_hrus resolves persisted HRU CN fields from run-scoped geneva/data/cn_table.csv before writing hru_table.parquet; missing exact rows fall back explicitly
Frequency panel matrix + unavailable reasons Implemented CLIGEN always attempted; NOAA optional
Runtime batch hyetograph distribution Implemented run_batch dispatches selected closed storm shape (uniform, neh4_type_b, type_i, type_ia, type_ii, type_iii) through Rust geneva_build_hyetograph
Storm-shape kernel dispatch module Implemented in Rust Shared closed enum + dispatch in geneva_core (storm_shape.rs, hyetograph.rs)
Flask routes + RQ tasks Implemented Single geneva_bp.py module
rq-engine Geneva API/state Implemented Includes chained run-workflow endpoint and revisioned state payload
Interactive summary query/report payload Implemented Marker/table selection contract live

3. Scope and Non-Goals

In scope (v1 baseline):

  • US-only workflow assumptions (NLCD + NRCS-compatible HSG source expectations).
  • HRU preparation from bound.tif, landuse, hydgrpdcd, optional burn severity.
  • Frequency-panel generation from CLIGEN and optional NOAA Atlas 14 artifacts.
  • Batch storm execution with per-storm artifacts and batch summary.
  • Interactive summary query/report payloads.
  • CN-table editing workflow with audit trail and optimistic concurrency.

Out of scope (still deferred):

  • Non-US taxonomy packs.
  • Snowmelt and rain-on-snow process representation.
  • Channel hydraulics/kinematic-wave routing and reservoir routing.
  • Mixed rainfall-excess process families in one run.

4. Scientific Basis and Conformance

Primary references remain:

  • RMRS-GTR-334 (Wildcat5 manual),
  • NRCS NEH 630 hydrology references,
  • SCS/TR-55 method family references.

Conformance posture:

  • RMRS method family and workflow sequencing remain normative.
  • Where implementation differs, deviations are documented explicitly below.

4.1 Conformance Deviations (Retained + Current)

Deviation ID Section Description Status
DEV-001 HRU collapse Minimum HRU area floor 2 ha and deterministic collapse Implemented
DEV-002 CN seeding Non-forest/non-shrub burn CN rows remain static in seed defaults Implemented (table workflow)
DEV-003 Frequency panel Duration interpolation disabled for panel materialization Implemented
DEV-004 Climate sourcing Dual-source panel strategy (CLIGEN always attempted; NOAA optional) Implemented
DEV-005 CN resolution Runtime HRU CN now resolves from run-scoped cn_table.csv at prepare_hrus persistence time; missing exact lookup rows fall back explicitly to the kernel proxy estimator Implemented behavior
DEV-006 Storm construction Batch storm-shape dispatch is now selected at runtime via closed enum with legacy-artifact compatibility warnings for old uniform-interim outputs Implemented behavior
DEV-007 Default HSG derivation Dominant-soil derivation path is not implemented; only explicit default_hsg_code is used Active gap
DEV-008 Enable/disable semantics enabled remains effectively true when mod is present (membership-driven) Implemented behavior
DEV-009 Collapse failure policy No compatible recipient does not fail run; donor HRU is retained with warning Implemented behavior

Wildcat5 workbook/macro references remain staged under:

  • wepppy/nodb/mods/geneva/resources/Wildcat5/
  • extracted VBA modules under .../extracted_macros/wildcat5dec072015-64bits/

Policy remains:

  • do not execute VBA at runtime,
  • port equations/algorithms into owned Python/Rust code,
  • keep parity/unit tests around ported logic.

5. Runtime Architecture (Current)

5.1 Python (wepppy) orchestration

Geneva NoDb facade:

  • wepppy/nodb/mods/geneva/geneva.py

Collaborators:

  • config_service.py
  • hsg_assignment_service.py
  • hru_preparation_service.py
  • frequency_panel_service.py
  • batch_run_service.py
  • results_service.py
  • report_payload_service.py
  • cn_table_service.py
  • artifact_io.py
  • kernel_gateway.py

5.2 Rust (wepppyo3) kernel boundary

PyO3 adapter entrypoints:

  • geneva_prepare_hrus
  • geneva_build_frequency_panel
  • geneva_build_hyetograph
  • geneva_run_batch
  • geneva_validate_uh (stub)

Core crate modules:

  • hru.rs
  • frequency_panel.rs
  • cn.rs
  • uh.rs
  • convolution.rs
  • hyetograph.rs (selected storm-shape dispatch wired from Python run_batch)
  • storm_shape.rs (shared storm-shape enum and validation)

6. Guardrails (Hard Requirements)

6.1 WBT-only

Geneva rejects non-WBT delineations with:

  • code: unsupported_backend
  • message: Geneva requires the WBT delineation backend.

6.2 US-only / dataset compatibility

Geneva rejects unsupported domain conditions with:

  • code: unsupported_domain
  • message: Geneva v1 is US-only and requires NLCD + US NRCS-compatible HSG inputs.

Current checks:

  • US envelope: -179.5 <= lng <= -64.0 and 17.0 <= lat <= 72.5.
  • NLCD compatibility by landuse.nlcd_db/landuse.lc_fn containing nlcd.
  • HSG compatibility by soils.ssurgo_db/soils.ssurgo_fn containing ssurgo or hydgrpdcd.

6.3 Enablement semantics

Current behavior is membership-driven:

  • Geneva is auto-enabled on initialization.
  • set_enabled(false) does not disable runtime execution; effective enabled remains true.
  • Config payload still contains enabled, but it tracks effective state, not a hard off switch.

7. Configuration Contract (Current)

Schema version: 1

Current config fields:

  • enabled (effective true while mod is present)
  • lambda_mode: 0.20 | 0.05 (default 0.20)
  • uh_method: scs_triangular | scs_curvilinear (default scs_triangular)
  • default_hsg_code: 1 | 2 | 3 | 4 | null (integer or null only)
  • unresolved_hsg_policy: error | assume_d (default assume_d)
  • strict_burn_nodata: boolean (default false)
  • allow_cross_hsg_merge: boolean (default false)
  • hydrophobic_forest_high: boolean (default true)
  • hydrophobic_forest_moderate: boolean (default false)
  • hydrophobic_shrub_high: boolean (default true)
  • hydrophobic_shrub_moderate: boolean (default false)
  • min_hru_area_ha: numeric >= 2.0 (default 2.0)

Validation highlights:

  • boolean fields reject string booleans,
  • default_hsg_code rejects string numerals,
  • min_hru_area_ha < 2.0 is rejected,
  • config updates clear runtime results/status caches when values change after prepared/running/completed states.

8. Input Contract and CN-Table Workflow

8.1 HRU prepare input references

Required raster references:

  • bound_tif
  • landuse_tif
  • hydgrpdcd_tif

Optional:

  • burn_severity_tif

Current source resolution behavior:

  • required refs default from watershed/landuse/soils NoDb objects,
  • optional burn ref can be auto-discovered from Disturbed (sbs_4class_path, then disturbed_cropped),
  • auto-discovered Disturbed burn refs are materialized as geneva/inputs/burn_severity_4class.tif on the canonical bound.tif grid with nearest-neighbor reprojection before the kernel request,
  • explicit burn_severity_tif overrides are passed through unchanged so callers can supply a deliberate raster contract,
  • required paths must exist or request fails,
  • missing optional burn path is dropped silently (optional-only behavior).

8.2 Run-scoped CN table (geneva/data/cn_table.csv)

Current implemented workflow:

  • initialized from module seed: wepppy/nodb/mods/geneva/data/geneva_cn_table_us_v1_seed.csv
  • recreated when missing,
  • reset endpoint restores seed deterministically,
  • optimistic concurrency required on modify (if_match_sha256),
  • append-only audit log at geneva/data/cn_table_audit.jsonl.

Current canonical persisted columns:

  • nlcd_class
  • nlcd_label
  • hsg
  • burn_severity
  • hydrophobic
  • cn_arc_ii
  • antecedent_condition_source
  • source
  • notes

Migration behavior:

  • legacy files missing antecedent_condition_source are migrated to schema v1 with default arc_ii_seed.

Modify behavior constraints:

  • non-empty row list required,
  • duplicate composite keys rejected,
  • payload must include all existing keys (row deletions rejected),
  • accepts body token and/or X-If-Match-Sha256 header token.

8.3 Runtime CN-table consumption

cn_table.csv is the active runtime source for persisted HRU CN values.

  • GenevaHruPreparationService resolves HRU cn_arc_ii by exact lookup on:
    • nlcd_class
    • hsg
    • burn_severity
    • hydrophobic
  • The resolved CN is written into geneva/hru_table.parquet, and downstream run_batch uses that persisted parquet.
  • Editing geneva/data/cn_table.csv does not retroactively mutate an existing hru_table.parquet; rerun prepare_hrus to regenerate the artifact.
  • prepare_hrus now invalidates its cached summary when the CN-table hash changes, so rerunning the task after a CN-table edit refreshes hru_table.parquet even when force_rebuild=false.
  • When an exact CN-table row is missing, Geneva keeps the kernel-estimated CN for that HRU and marks the persisted row with:
    • cn_source = "geneva_proxy_cn_v1_fallback_missing_row"
    • warning cn_table_missing_exact_row

9. HRU Preparation Contract (Current)

Entry: geneva_prepare_hrus kernel call via GenevaHruPreparationService.

9.1 Kernel request fields

Python sends:

  • kernel_schema_version = 1
  • raster refs (bound_tif, landuse_tif, hydgrpdcd_tif, optional burn_severity_tif)
  • default_hsg_code (user override only)
  • default_hsg_derivation (currently user_override or null)
  • unresolved_hsg_policy
  • strict_burn_nodata
  • allow_cross_hsg_merge
  • min_hru_area_ha
  • hydrophobic toggles

9.2 HRU key and burn/hydrophobic rules

Kernel HRU key dimensions:

  • landuse_class
  • hsg_group
  • burn_severity_class
  • hydrophobic_class
  • is_water

Burn mapping:

  • 0 -> unburned
  • 1 -> low
  • 2 -> moderate
  • 3 -> high
  • nodata in-bound:
    • error when strict_burn_nodata=true,
    • mapped to unburned with warning otherwise.

Hydrophobic toggles:

  • forest classes 41,42,43 use forest toggles for moderate/high burn,
  • shrub class 52 uses shrub toggles for moderate/high burn,
  • all other combinations resolve to false.

9.3 HSG handling

Hydgrpdcd mapping domain:

  • 1->A, 2->B, 3->C, 4->D
  • 0 or nodata => unresolved
  • 5/6/7 and other unexpected codes => warning + unresolved path

Fallback chain:

  1. coded lookup
  2. default_hsg_code (if provided)
  3. unresolved policy:
  • error => fail
  • assume_d => coerce to D with warning

9.4 Minimum HRU area collapse

Current enforced floor:

  • min_hru_area_ha >= 2.0

Collapse compatibility:

  • must match is_water, landuse, burn, hydrophobic
  • must match hsg unless allow_cross_hsg_merge=true

Recipient selection order:

  1. smallest abs(delta_cn_arc_ii)
  2. largest recipient area
  3. lexical hru_id

Current no-recipient behavior:

  • donor HRU is retained (warning collapse_no_compatible_recipient),
  • run does not fail solely because no compatible recipient exists.

9.5 Runtime CN resolution path

Current runtime path:

  • kernel still computes a provisional CN via estimate_cn_arc_ii(...),
  • Python prepare_hrus replaces persisted HRU CN fields from the run-scoped CN table when an exact lookup row exists,
  • persisted table-backed rows use cn_source = "geneva_cn_table_csv_v1",
  • persisted fallback rows use cn_source = "geneva_proxy_cn_v1_fallback_missing_row".

Current provisional kernel estimator:

  • base CN by NLCD class (11=100, 41-43=55, 52=65, 71=68, 81=74, 82=78, else 75)
  • HSG adjustment (A=0, B=+7, C=+14, D=+21)
  • burn adjustment (unburned=0, low=+2, moderate=+5, high=+8)
  • hydrophobic adjustment (+6 when hydrophobic_class=true)
  • final clamp: [30, 100]
  • cn_lambda_005 derived with RMRS-style transform and cap behavior for cn_arc_ii > 98.5.

9.6 HRU outputs and persisted artifacts

Persisted artifacts:

  • geneva/hru_table.parquet
  • geneva/hru_map.tif (HRU raster index map; int32, nodata=0)
  • geneva/hru_map_legend.json (map value-to-HRU legend and mapping diagnostics)

Current generation path:

  • geneva_prepare_hrus (wepppyo3) now generates the HRU map and legend in the Rust hot path.
  • Python GenevaHruPreparationService passes kernel output paths (hru_map_output_tif, hru_map_legend_output_json) and validates artifact materialization plus returned hru_map summary metadata.

Persisted columns:

  • hru_id
  • area_m2
  • area_ac
  • area_fraction
  • landuse_class
  • hsg_group
  • burn_severity_class
  • hydrophobic_class
  • is_water
  • cn_arc_ii
  • cn_lambda_020
  • cn_lambda_005
  • antecedent_condition_source
  • cn_source
  • hsg_source
  • collapsed_from_hru_ids
  • warnings

Persisted summary:

  • geneva/hru_prepare_summary.json
  • current summary includes hru_count, hru_area_total_m2, hru_area_total_acres, hsg_provenance_counts, warnings, refs, artifact relpaths, and CN-table lookup metadata (lookup_sha256, runtime source, fallback count).
  • current summary artifacts include hru_map_relpath and hru_map_legend_relpath.
  • current summary hru_map block includes:
    • nodata_value
    • hru_value_count
    • fallback_id_match_count
    • mapping_status (complete|partial)
    • active_cell_count, mapped_cell_count, unmapped_cell_count
    • unresolved_component_count and bounded unresolved_component_samples.

10. Frequency Panel Contract (Current)

Entry: geneva_build_frequency_panel.

Defaults:

  • durations: [5,10,15,30,60,120,180,360,720,1440]
  • ARI years: [1,2,5,10,25,50,100]
  • distribution_type = neh4_type_b
  • allow_duration_interpolation = false

Sources:

  • CLIGEN default: climate/wepp_cli_pds_mean_metric.csv
  • NOAA default: climate/atlas14_intensity_pds_mean_metric.csv

CLIGEN materialization:

  • Storm depth (mm) + Storm duration (hours) rows produce the duration/ARI cells they describe.
  • Available CLIGEN intensity rows such as 10-min intensity (mm/hour), 15-min intensity (mm/hour), 30-min intensity (mm/hour), and 60-min intensity (mm/hour) also produce duration/ARI cells.
  • Intensity-derived cell depth is intensity_mm_per_hr * duration_minutes / 60.
  • Existing depth/duration cells take precedence if an intensity row would duplicate the same (duration_minutes, ari_years) key.

CLIGEN normalization shim (current implementation detail):

  • if CLIGEN file uses Precipitation depth (mm): row label, service writes normalized copy with Storm depth (mm): to:
    • geneva/normalized_sources/wepp_cli_pds_mean_metric_kernel.csv
  • normalization preserves CLIGEN intensity rows so they remain available to the kernel.

NOAA normalization shim (current implementation detail):

  • NOAA Atlas 14 intensity exports can include rounded zero rows for long durations, for example 7-day and longer rows with 0 intensities at low ARI.
  • Before calling the kernel, the service writes a normalized copy to:
    • geneva/normalized_sources/atlas14_intensity_pds_mean_metric_kernel.csv
  • The normalized copy omits NOAA duration rows containing any non-finite or non-positive intensity value and preserves valid rows plus metadata.
  • If a requested duration is omitted this way, the panel reports existing unavailable-cell reasons such as duration_unavailable instead of failing the whole frequency-panel build.

Output invariants:

  • persisted to geneva/frequency_panel.json
  • service cache reuse is distribution-aware: cached panel is reused only when requested distribution_type matches persisted panel distribution; otherwise panel is rebuilt
  • cell availability is available|unavailable
  • reason_code must be null when available
  • unavailable reason codes are:
    • duration_unavailable
    • ari_unavailable
    • source_missing
  • cells sorted deterministically by (datasource_id, duration_minutes, ari_years, storm_id).

11. Batch Run and Hydrograph Contract (Current)

Entry: geneva_run_batch (Python orchestrates per-storm kernel calls).

11.1 Request validation

schema_version=1 and:

  • event_filter.datasource_ids optional list of cligen_freq|noaa14_pds
  • event_filter.durations_minutes optional positive int list
  • event_filter.ari_years optional positive int list
  • hyetograph.distribution_type must be one of:
    • uniform
    • neh4_type_b
    • type_i
    • type_ia
    • type_ii
    • type_iii
  • hyetograph.time_step_minutes > 0
  • hyetograph.time_step_minutes must evenly divide each selected storm duration for runtime CN/hydrograph convolution (non-divisible combinations are rejected as invalid_input before kernel run-batch execution)
  • hyetograph.distribution_type must match the persisted frequency-panel distribution_type; callers must rebuild panel first when switching storm shape
  • exactly one of:
    • runoff_model.tc_hours, or
    • runoff_model.timing_method (kirpich|kent|simas)

Prerequisites:

  • geneva/frequency_panel.json must exist
  • geneva/hru_table.parquet must exist and be non-empty

11.2 Current storm construction in Python

Current runtime behavior uses Rust geneva_build_hyetograph per selected panel cell:

  • uses selected cell duration_minutes and depth_mm
  • uses request hyetograph.distribution_type + time_step_minutes
  • dispatches by closed storm-shape enum:
    • uniform: linear cumulative rainfall from 0 to duration depth
    • neh4_type_b: legacy Geneva Type B curve
    • type_i|type_ia|type_ii|type_iii: embedded-window extraction from checked-in 24-hour WinTR-20 source curves
  • persists selected distribution and source metadata in:
    • geneva/storm_inputs.json
    • geneva/storms/<storm_id>/hyetograph.parquet
    • geneva/storms/<storm_id>/summary.json
    • geneva/batch_summary.json

Timing fallback when timing_method is used:

  • kirpich: tc = clamp(0.6 * sqrt(area_km2), 0.25, 6.0)
  • kent: tc = clamp(0.8 * sqrt(area_km2), 0.25, 6.0)
  • simas: tc = clamp(1.0 * sqrt(area_km2), 0.25, 6.0)

11.3 Kernel run-batch behavior

Kernel receives per-storm payload with:

  • lambda_mode, uh_method, tc_hours
  • time_minutes, cumulative_rainfall_mm
  • HRU rows (hru_id, area_m2, cn_lambda_020)

Kernel computes:

  • CN excess (0.20 and 0.05 forms with 98.5 cap behavior)
  • composite excess
  • unit hydrograph (scs_triangular|scs_curvilinear)
  • hydrograph, summary metrics, diagnostics

11.4 Persisted storm and batch artifacts

Per completed storm:

  • geneva/storms/<storm_id>/hyetograph.parquet
  • geneva/storms/<storm_id>/excess_hyetograph.parquet
  • geneva/storms/<storm_id>/hydrograph.parquet
  • geneva/storms/<storm_id>/summary.json

Batch-level:

  • geneva/storm_inputs.json
  • geneva/batch_summary.json

Run status aggregation:

  • failed if any available storm fails
  • else completed_with_gaps if unavailable panel cells are present
  • else completed

11.5 Watershed scale warnings

Thresholds:

  • warning: >25 km2
  • severe: >100 km2
  • extreme: >250 km2

Warning payload includes:

  • code point_rainfall_assumption
  • area values (km2, mi2, acres)
  • threshold details
  • arf_method=constant_1.0, arf_value=1.0, uniform_rainfall_assumed=true

11.6 Implemented storm-shape runtime contract

Status: implemented by docs/work-packages/20260428_geneva_storm_shape_control/.

Geneva Storm Shape has six closed enum values:

ID Label Implementation source
uniform Uniform Linear cumulative event rainfall.
neh4_type_b NEH-4 B Existing Geneva Rust normalized Type B ordinates.
type_i Type I NRCS legacy 24-hour cumulative mass curve generated from WinTR-20 output.
type_ia Type IA NRCS legacy 24-hour cumulative mass curve generated from WinTR-20 output.
type_ii Type II NRCS legacy 24-hour cumulative mass curve generated from WinTR-20 output.
type_iii Type III NRCS legacy 24-hour cumulative mass curve generated from WinTR-20 output.

Type I/IA/II/III source and provenance requirements:

  • Authoritative technical basis: NRCS Title 210, National Engineering Handbook, Part 630, Chapter 4, "Storm Rainfall Depth and Distribution" (Aug 2019).
  • Implementation source of truth: checked-in WinTR-20-derived artifacts under /workdir/wepppyo3/geneva_core/resources/:
    • raw WinTR-20 distribution output: nrcs_legacy_24h_distributions.wintr20_raw.txt
    • normalized 24-hour cumulative ordinate table: nrcs_legacy_24h_distributions.csv
    • provenance metadata: nrcs_legacy_24h_distributions.metadata.json
  • Required metadata fields: WinTR-20 version, generation date, raw_output_filename, raw_output_sha256, export_mode, time_increment_hours, decimal_precision, rounding_policy, post_processing_steps, normalized_csv_sha256, row count, and monotonic endpoint checks.
  • Source table time increment must be recorded. A 0.1-hour source increment is acceptable only if validation against NEH Chapter 4 Figure 4-31 passes; otherwise regenerate/export a finer source table before implementation.
  • Type II embedded-duration ratios must match NEH Chapter 4 Figure 4-31 within absolute fraction tolerance <= 0.003. Tolerance relaxation requires a review artifact explaining why the source export, interpolation, and validation target are still authoritative.
  • Secondary web tables are not authoritative implementation sources. They may be used only for sanity checks.

Type I/IA/II/III event-duration algorithm:

  1. Treat the 24-hour table as a piecewise-linear cumulative mass curve F(t) over 0 <= t <= 24 hours.
  2. Validate 0 < duration_minutes <= 1440, depth_mm > 0, and time_step_minutes > 0.
  3. Convert event duration to hours, d = duration_minutes / 60.
  4. For d == 24, use the full source curve.
  5. For d < 24, find the window start a in [0, 24 - d] that maximizes F(a + d) - F(a).
  6. Candidate starts must include source table times and source table times minus d, clipped to [0, 24 - d].
  7. If candidates tie within tolerance, choose the candidate closest to 12 - d / 2; if still tied, choose the earliest.
  8. Let r = F(a + d) - F(a). Fail if r <= 0.
  9. Build the output time vector with 0 and exact duration_minutes endpoints. Intermediate points are regular time_step_minutes multiples strictly inside the duration; if time_step_minutes >= duration_minutes, output only the two endpoints. If duration is not evenly divisible by the step, the final interval is shorter.
  10. For output time t in the event, compute event_fraction(t) = (F(a + t_hours) - F(a)) / r.
  11. Force the first and final output points to 0.0 and 1.0, enforce monotonicity within tolerance, and set cumulative_rainfall_mm = event_fraction(t) * depth_mm.

This is intentionally an embedded-window extraction, not full-curve compression. Geneva frequency-panel cells provide depth for the selected duration; for example, a 60-minute event uses the selected 60-minute depth. The Type II 60-minute hyetograph therefore comes from the maximum embedded 60-minute window of the 24-hour Type II curve, normalized to the selected 60-minute depth.

Type I/IA/II/III output metadata must include:

  • source_distribution_type
  • source_curve_duration_hours=24
  • extraction_start_hours
  • extraction_end_hours
  • extraction_ratio_to_24h
  • event_depth_is_duration_depth=true
  • source_table_sha256

NRCS cautions that legacy Type I/IA/II/III regional distributions can be inconsistent with NOAA Atlas 14 site-specific ratios. Geneva must therefore expose these shapes as explicit user-selected assumptions, not as an automatic regional recommendation.

12. State, Results, Query, and Report Contracts (Current)

12.1 Geneva lifecycle states

  • idle
  • prepared
  • running
  • completed
  • completed_with_gaps
  • failed

12.2 Status and results payloads

status_payload includes:

  • status, status_message
  • progress (completed, total, unit, percent, updated_at)
  • active_job_id, last_job_id

results_payload includes:

  • status
  • last_prepare_summary
  • last_run_summary
  • warnings, errors

state_payload additionally includes:

  • state_version=1
  • enabled
  • config_snapshot
  • artifact readiness flags (hru_table_ready, hru_map_ready, hru_map_legend_ready, frequency_panel_ready, batch_summary_ready)
  • updated_at

12.3 Query/report summary payload

query_summary_payload provides:

  • filters (datasource_id, ari_years, measure)
  • filter_options:
    • datasource_ids = [all, cligen_freq, noaa14_pds]
    • datasource_availability
    • ari_years
    • measures = [peak_discharge, runoff_depth, runoff_volume]
    • duration_minutes
  • chart grouped by ARI, marker-labeled by duration
  • event_table with status and metrics
  • selected_storm_id sync key
  • sanitized warnings and errors

Current row status resolution precedence:

  1. panel availability (unavailable if not available),
  2. run summary failed/completed sets,
  3. fallback to storm summary status.

Chart includes completed storms only.

12.4 HRU Choropleth Measure Contract (WP01/WP02)

Status: normative contract defined in WP01 and implemented in WP02 runtime paths (run_batch materialization + HRU-map query surface).

12.4.1 Measure-scope matrix

Measure ID Watershed event table/query summary HRU choropleth map Canonical unit Scope rationale
peak_discharge Yes No m3_s peak_discharge is computed from the watershed-composite hydrograph and remains a watershed summary metric. HRU-level mapping would imply a non-canonical disaggregation and is intentionally disallowed.
runoff_depth Yes Yes mm Depth is valid as both watershed summary and per-HRU map metric.
runoff_volume Yes Yes m3 Volume is additive across HRUs and valid for map display.
hru_peak_runoff No Yes m3_s HRU-local hydrograph peak derived from each HRU's own excess series, HRU area, selected uh_method, and selected tc_hours. It is not a watershed metric.

query_summary_payload.filter_options.measures remains [peak_discharge, runoff_depth, runoff_volume] for watershed summary exploration. HRU choropleth consumers must treat the HRU-mapable subset as [runoff_depth, runoff_volume, hru_peak_runoff] only.

12.4.2 Canonical keys and joins

Event identity contract:

  • primary event key: storm_id
  • required event dimensions: datasource_id, duration_minutes, ari_years, distribution_type
  • canonical event row source: frequency panel cell plus storms/<storm_id>/summary.json

HRU identity contract:

  • primary HRU key: hru_id from hru_table.parquet
  • raster-value join key: hru_value from hru_map_legend.json rows[*].hru_value
  • canonical crosswalk: hru_map_legend.json rows[*] where rows[*].hru_id <-> rows[*].hru_value

Required join behavior for query/report consumers:

  1. Join event rows to HRU measure rows on storm_id.
  2. Join HRU measure rows to HRU attributes/geometry on hru_id.
  3. If a geometry payload is keyed by raster value, resolve through hru_map_legend.json (hru_value -> hru_id) before joining measure rows.

12.4.3 Canonical HRU event-measure row contract

Additive artifact contract (materialized in WP02):

  • path: geneva/hru_event_measure_rows.parquet
  • schema version field: schema_version (initial value 1)
  • row granularity: one row per (storm_id, hru_id, measure_id)

Canonical columns:

Column Type Contract
schema_version integer Must be 1 for first release.
storm_id string Non-empty; joins to event-table storm_id.
datasource_id string enum `cligen_freq
duration_minutes integer Positive; copied from panel cell.
ari_years integer Positive; copied from panel cell.
distribution_type string enum Must match storm summary assumptions for the stored event.
hru_id string Non-empty; joins to hru_table.parquet hru_id.
hru_value integer Positive; joins to hru_map_legend.json rows[*].hru_value.
measure_id string enum `runoff_depth
value float Numeric measure value.
unit string enum mm when measure_id=runoff_depth; m3 when measure_id=runoff_volume; m3_s when measure_id=hru_peak_runoff.

HRU choropleth row-set uniqueness must hold on: (storm_id, hru_id, measure_id).

hru_peak_runoff derivation contract:

  • source field: run_batch hru_excess[].peak_runoff_m3_s
  • computation path: per-HRU incremental_excess_mm convolved with the selected Geneva unit hydrograph and that HRU's area_m2
  • prohibited shortcut: do not area-split watershed summary_metrics.peak_discharge to infer HRU peaks.

12.4.4 Backward-compatible behavior for legacy runs

Legacy runs created before WP02 may not contain geneva/hru_event_measure_rows.parquet.

Required compatibility behavior:

  • watershed summary query/report (query_summary_payload) remains available and unchanged.
  • HRU choropleth data requests against runs missing the artifact must return a contract-compliant unavailable response (rows=[]) rather than raising unhandled exceptions.
  • unavailable responses for this case must include reason_code=legacy_hru_event_measures_missing.
  • HRU choropleth requests with measure_id=peak_discharge must fail validation with explicit scope error code unsupported_measure_scope.

12.4.5 Query response envelope for HRU map rows (WP02)

HRU map row queries return an additive contract envelope:

  • schema_version (current 1)
  • filters (storm_id, measure_id)
  • availability:
    • status = available | unavailable
    • reason_code (legacy_hru_event_measures_missing when unavailable)
    • artifact_path (canonical geneva/hru_event_measure_rows.parquet)
  • query (query-engine style payload used for retrieval)
  • records (row list; empty when unavailable)
  • schema (present when include_schema=true; otherwise null)
  • row_count
  • warnings, errors

Error behavior:

  • validation failures (for example unsupported measure scope) return the Geneva error envelope with code unsupported_measure_scope;
  • legacy-missing-artifact is represented as availability.status=unavailable with HTTP 200 and empty row set.

12.4.6 Query response envelope for HRU map geometry (WP03)

HRU map geometry queries return an additive contract envelope:

  • route: POST /runs/<runid>/<config>/query/geneva/hru_map_features
  • schema_version (current 1)
  • availability:
    • status = available | unavailable
    • reason_code:
      • hru_map_missing when geneva/hru_map.tif is absent
      • hru_map_legend_missing when geneva/hru_map_legend.json is absent
    • artifact_path
  • join_keys:
    • primary = hru_value
    • secondary = hru_id
  • feature_collection (GeoJSON FeatureCollection, WGS84)
  • feature_count
  • bounds_wgs84 ([min_x, min_y, max_x, max_y] or null)
  • warnings, errors

Geometry feature properties include:

  • hru_value (primary join key for map rows),
  • hru_id (secondary join key),
  • and legend-derived metadata fields (landuse_class, hsg_group, burn_severity_class, hydrophobic_class, is_water) when present.

12.5 Per-Storm HRU Erosion Extension (Design Specification)

Status: design contract only; not implemented in the current baseline.

Scientific posture:

  • Per-storm erosion is an event sediment-generation estimate, not a reuse of the long-term annual RUSLE A raster.
  • The defensible near-term bridge is an opt-in Modified Universal Soil Loss Equation family calculation that uses Geneva event runoff plus RUSLE factor rasters.
  • The output is a hillslope/HRU sediment generation screening product. It is not channel delivery, not deposition, not gully erosion, and not a calibrated post-fire WEPP replacement.
  • The reason to keep this in the Geneva/Wildcat lineage is predictability: results should be traceable to a small set of event rainfall, runoff, HRU, and factor inputs that can be conceptually audited without requiring a full diagnosis of WEPP model state dynamics.
  • WEPP single-storm and continuous simulations remain important comparison tools, but they are not automatically a better answer for this use case. Local review experience, including Scott Sheppard's single-storm investigation, found peak-flow behavior and single-storm interpretation can depend strongly on kslast and related state/parameter choices.
  • Geneva event erosion is intended to support transparent relative comparison when WEPP continuous or single-storm results are hard to interpret because land-cover, soil-storage, burn-severity parameterization, or return-period T-statistic randomness dominates the analysis.

Reviewed model options:

Option Fit for Geneva Decision
MUSLE / SWAT-style HRU event sediment yield Strongest small extension because it replaces annual rainfall erosivity with event runoff volume and peak runoff rate while retaining K, LS, C, and P factors. Adopt as the v1 design path under musle_hru_event_v1.
HEC-HMS Modified USLE event method Useful independent engineering precedent for the same runoff-volume/peak-rate family. Use as terminology and QA precedent, not a separate formula contract.
AnnAGNPS/HUSLE delivery-ratio methods More suitable when estimating sediment delivered to a reach or watershed point. Defer; this requires routing and delivery semantics beyond Geneva v1 HRU maps.
WEPP single-storm or watershed erosion Process-based comparison path, but not a clean default for Geneva event erosion because single-storm outputs can be highly sensitive to kslast, antecedent/storage state, land-cover and burn-severity parameterization, and return-period storm sampling choices. Keep as an external comparison/validation path; do not make it the required or preferred basis for Geneva per-storm HRU estimates.
Design-storm RUSLE R surrogates from precipitation-frequency intensity Useful precedent for separate design-storm visualization, but mixes single-event assumptions with an annual R factor contract. Do not use for Geneva per-storm erosion.

Normative v1 model ID: musle_hru_event_v1.

Formula contract:

sed_t = 11.8 * (Qsurf_mm * qpeak_m3_s * area_ha)^0.56
        * factor_product * cfrg_factor

factor_product = area_weighted_mean(K * LS * C * P) over valid RUSLE cells in the HRU

Field definitions:

  • sed_t: estimated event sediment generation for one HRU, metric tons.
  • Qsurf_mm: Geneva HRU event runoff depth from the final hru_excess[].cumulative_excess_mm value.
  • qpeak_m3_s: HRU-local event peak runoff rate, not watershed peak discharge apportioned by area.
  • area_ha: valid HRU source area in hectares used for the event estimate.
  • K, LS, C, and P: gridded RUSLE factor rasters from the same project.
  • cfrg_factor: coarse-fragment factor; fixed to 1.0 in v1 unless a separately documented coarse-fragment raster/contract is implemented.

Required inputs when a project has both rusle and geneva:

  • Geneva artifacts:
    • geneva/hru_table.parquet
    • geneva/hru_map.tif
    • geneva/hru_map_legend.json
    • geneva/hru_event_measure_rows.parquet
    • geneva/batch_summary.json
    • completed per-storm hru_excess rows, or an equivalent persisted HRU excess series artifact
  • RUSLE artifacts:
    • rusle/manifest.json
    • selected rusle/k_<mode>.tif
    • selected rusle/c_<mode>.tif
    • rusle/ls.tif
    • rusle/p.tif

Explicit non-inputs:

  • Do not use rusle/r.tif; annual rainfall erosivity is replaced by event runoff volume and peak runoff rate.
  • Do not use rusle/a_<c_mode>_<k_mode>.tif; that raster is an annual long-term product and cannot be repartitioned into event loss.
  • Do not estimate qpeak_m3_s by multiplying watershed peak discharge by HRU area fraction; that creates a false precision and breaks the event-flow contract.

Grid and aggregation requirements:

  • hru_map.tif, ls.tif, selected k, selected c, and p must be on the same grid in v1: identical CRS, transform, shape, and pixel alignment.
  • If grids are not identical, the erosion extension must return unavailable with reason_code=rusle_geneva_grid_mismatch; it must not silently resample factor rasters.
  • Aggregate RUSLE factors by HRU using only cells with finite values in every selected factor raster and matching the HRU raster value.
  • Compute and persist factor_product as the area-weighted mean of K * LS * C * P, not as mean(K) * mean(LS) * mean(C) * mean(P), so within-HRU spatial covariation is preserved.
  • Persist component means (k_factor_mean, ls_factor_mean, c_factor_mean, p_factor_mean) for audit and QA, but use factor_product in the equation.
  • Persist valid_factor_area_fraction; HRUs below a configured validity threshold are unavailable with reason_code=insufficient_valid_factor_area.
  • Water/out-of-domain HRUs are unavailable with reason_code=out_of_domain_hru, not silently converted to zero erosion.

HRU peak-runoff substrate status:

  • Implemented runtime substrate:
    • Rust run_batch emits hru_excess[].peak_runoff_m3_s and hru_excess[].time_to_peak_minutes.
    • peak_runoff_m3_s is computed by applying the selected Geneva unit-hydrograph family to each HRU's own incremental excess series and HRU area.
    • geneva/hru_event_measure_rows.parquet materializes this as measure_id=hru_peak_runoff, unit=m3_s.
  • Erosion extension requirement:
    • Treat this HRU-local value as qpeak_m3_s input for musle_hru_event_v1; do not derive it by watershed peak area apportionment.
    • The HRU hydrograph implied by this value is local hillslope/HRU response before channel routing and must stay labeled as local response metadata.
    • If a completed storm/HRU row lacks a valid local peak, that erosion row must be unavailable with reason_code=hru_peak_runoff_unavailable.

Output artifact contract:

  • Batch-level row set: geneva/hru_event_erosion_rows.parquet
  • Schema version: 1
  • Row granularity: one row per available (storm_id, hru_id, erosion_model_id).

Canonical columns:

Column Type Contract
schema_version integer Must be 1 for this design.
storm_id string Joins to the Geneva event-table storm key.
datasource_id string enum `cligen_freq
duration_minutes integer Positive; copied from the panel cell.
ari_years integer Positive; copied from the panel cell.
distribution_type string enum Must match the storm hyetograph assumptions.
hru_id string Joins to hru_table.parquet.
hru_value integer Joins to hru_map_legend.json.
erosion_model_id string enum Must be musle_hru_event_v1 for v1.
runoff_depth_mm float Final HRU cumulative excess depth.
runoff_volume_m3 float HRU runoff volume used for QA.
peak_runoff_m3_s float HRU-local peak runoff rate.
area_ha float Valid source area used in the MUSLE term.
k_factor_mean float HRU area-weighted mean selected K factor.
ls_factor_mean float HRU area-weighted mean LS factor.
c_factor_mean float HRU area-weighted mean selected C factor.
p_factor_mean float HRU area-weighted mean P factor.
factor_product float Area-weighted mean of K * LS * C * P.
cfrg_factor float 1.0 in v1 unless a coarse-fragment contract is added.
valid_factor_area_fraction float Fraction of HRU area with finite factor inputs.
erosion_mass_t float Estimated sediment generation for the storm/HRU.
erosion_yield_t_ha float erosion_mass_t / area_ha.

Uniqueness must hold on (storm_id, hru_id, erosion_model_id).

Unavailable diagnostics are not written as numeric rows in v1. They are summarized in geneva/hru_event_erosion_summary.json with counts by reason_code, representative samples, source artifact hashes, selected RUSLE modes, and the configured valid_factor_area_fraction threshold.

Cache and invalidation requirements:

  • Recompute erosion rows whenever any of these source hashes change:
    • geneva/hru_table.parquet
    • geneva/hru_map.tif
    • geneva/hru_map_legend.json
    • geneva/hru_event_measure_rows.parquet
    • geneva/batch_summary.json
    • rusle/manifest.json
    • selected RUSLE K, LS, C, or P rasters
  • Persist those hashes in geneva/hru_event_erosion_summary.json.
  • If RUSLE is missing or stale, return unavailable with reason_code=rusle_factors_missing_or_stale; do not fall back to constants.

Interpretation and UI wording:

  • Preferred label: Estimated event sediment generation (MUSLE).
  • Required qualifier: Screening estimate for relative event comparison; not routed sediment delivery and not a calibrated WEPP replacement.
  • Map units may be t/ha for intensity-style choropleths and t for total HRU mass tables.
  • Default UI state should hide this layer unless both Geneva and RUSLE artifacts are ready and the user explicitly selects the erosion estimate.

Validation plan before implementation:

  • Unit-test equation evaluation, zero-runoff behavior, unavailable diagnostics, factor-product aggregation, and source-hash invalidation.
  • Build a synthetic HRU raster/factor-grid fixture where the expected area-weighted K * LS * C * P product is hand-computable.
  • Compare HRU-local peak-flow derivation against the existing watershed hydrograph path for a one-HRU run; the HRU and watershed peaks should match within numeric tolerance when there is exactly one HRU.
  • Validate multi-HRU behavior with a fixture where watershed peak disaggregation would produce a different result, proving that the implementation uses HRU-local hydrographs.
  • For scientific QA, compare event-rank ordering and magnitude against independent observations where available and against WEPP continuous or single-storm outputs only as sensitivity/comparison evidence. QA notes must document kslast, land-cover, soil-storage, burn-severity, and return-period storm assumptions when WEPP is used as a comparator.

13. API Surface (Current)

13.1 Flask WEPPcloud routes (geneva_bp.py)

Config and task routes:

  • GET /runs/<runid>/<config>/api/geneva/config
  • POST /runs/<runid>/<config>/api/geneva/config
  • POST /runs/<runid>/<config>/tasks/geneva/prepare_hrus
  • POST /runs/<runid>/<config>/tasks/geneva/build_frequency_panel
  • POST /runs/<runid>/<config>/tasks/geneva/run_batch

Status/results/query/report:

  • GET /runs/<runid>/<config>/api/geneva/status
  • GET /runs/<runid>/<config>/api/geneva/results
  • GET /runs/<runid>/<config>/api/geneva/frequency_panel
  • GET /runs/<runid>/<config>/query/geneva/summary
  • POST /runs/<runid>/<config>/query/geneva/hru_map_rows
  • POST /runs/<runid>/<config>/query/geneva/hru_map_features
  • GET /runs/<runid>/<config>/report/geneva/summary

CN-table routes:

  • GET /runs/<runid>/<config>/modify_geneva_cn_table
  • GET /runs/<runid>/<config>/api/geneva/cn_table_meta
  • GET /runs/<runid>/<config>/api/geneva/cn_table_snapshot
  • POST /runs/<runid>/<config>/tasks/modify_geneva_cn_table
  • POST /runs/<runid>/<config>/tasks/reset_geneva_cn_table

Response-shape note:

  • most Geneva Flask endpoints return raw JSON payloads (jsonify(payload)),
  • POST /query/geneva/hru_map_rows returns top-level availability + filters + records payload (not wrapped),
  • POST /query/geneva/hru_map_features returns top-level availability + feature_collection payload (not wrapped),
  • CN-table meta/snapshot/reset use success_factory, so payload is wrapped under {"Content": ...}.

13.2 rq-engine Geneva routes (microservices/rq_engine/geneva_routes.py)

Enqueue routes:

  • POST /api/runs/{runid}/{config}/geneva/prepare-hrus
  • POST /api/runs/{runid}/{config}/geneva/build-frequency-panel
  • POST /api/runs/{runid}/{config}/geneva/run-batch
  • POST /api/runs/{runid}/{config}/geneva/run-workflow

State route:

  • GET /api/runs/{runid}/{config}/geneva/state

Workflow chaining:

  • run-workflow enqueues prepare -> panel -> run-batch dependencies,
  • workflow normalization forces:
    • prepare.force_rebuild = true
    • panel.rebuild = true

State response extras:

  • contract_version
  • deployment_revision
  • run_state_domain
  • run_state_revision
  • run_state_vector
  • etag
  • plus Geneva state_payload fields

13.3 Canonical error and enqueue envelopes

Current canonical error shape:

{
  "error": {
    "message": "Human-readable summary",
    "code": "error_code",
    "details": "or object"
  }
}

Canonical enqueue success shape (single-job endpoints):

{
  "job_id": "rq-...",
  "status_url": "/rq-engine/api/jobstatus/rq-...",
  "message": "Job enqueued."
}

Workflow enqueue success shape:

{
  "job_id": "prepare-job-id",
  "job_ids": {
    "prepare_hrus": "prepare-job-id",
    "build_frequency_panel": "panel-job-id",
    "run_batch": "run-job-id"
  },
  "status_url": "/rq-engine/api/jobstatus/prepare-job-id",
  "message": "Workflow enqueued."
}

14. UI Contract (Current)

Run-page Geneva control (controls/geneva_pure.htm + controllers_js/geneva.js):

  • state authority is rq-engine Geneva state endpoint,
  • one primary run action queues chained workflow (run-workflow),
  • config is auto-saved before queue submission when dirty,
  • control includes panel and run filters, CN-table launch, query/report launch links.

Summary report (reports/geneva/summary.htm + geneva_summary_report.js):

  • embeds summary payload in one JSON script node:
    • id="geneva-summary-payload"
    • type="application/json"
  • filter controls: datasource, ARI, measure,
  • marker/table selection synchronization via selected_storm_id,
  • datasource availability messaging (NOAA unavailable note).

15. Artifact Catalog (Current)

Under <run>/geneva/:

  • data/cn_table.csv
  • data/cn_table_audit.jsonl
  • hru_table.parquet
  • hru_prepare_summary.json
  • frequency_panel.json
  • storm_inputs.json
  • batch_summary.json
  • hru_event_measure_rows.parquet
  • storms/<storm_id>/hyetograph.parquet
  • storms/<storm_id>/excess_hyetograph.parquet
  • storms/<storm_id>/hydrograph.parquet
  • storms/<storm_id>/summary.json
  • optional normalization artifact:
    • normalized_sources/wepp_cli_pds_mean_metric_kernel.csv
    • normalized_sources/atlas14_intensity_pds_mean_metric_kernel.csv

WP02 production note:

  • hru_event_measure_rows.parquet is materialized during run_batch from completed storm hru_excess rows and frequency-panel event dimensions.
  • Legacy runs created before WP02 may not include this artifact; HRU map queries must return an unavailable response with reason_code=legacy_hru_event_measures_missing.

Future event-erosion design artifacts from Section 12.5:

  • hru_event_erosion_rows.parquet
  • hru_event_erosion_summary.json

These artifacts are not part of the current baseline and must not be assumed present by existing Geneva query/report routes.

16. Current Test/Validation Baseline

Geneva coverage currently includes:

  • schema contract tests (config, frequency panel, run batch validation),
  • guardrail tests (WBT/domain rejection),
  • facade/collaborator tests,
  • CN-table lifecycle/concurrency/audit tests,
  • query/report payload contract tests,
  • Flask route contract tests,
  • rq task wrappers and lock-retry behavior tests,
  • rq-engine route and state response tests,
  • integrated scenario matrix (completed, completed_with_gaps, warning propagation, collapse sensitivity checks).

Primary suites:

  • tests/nodb/mods/geneva/
  • tests/weppcloud/routes/test_geneva_bp.py
  • tests/weppcloud/routes/test_geneva_wp08_routes.py
  • tests/rq/test_geneva_rq.py
  • tests/microservices/test_rq_engine_geneva_routes.py

17. Deferred Work (Future Reference)

The following are intentionally tracked for follow-on implementation:

  • implement dominant-soil derivation for default_hsg_code when user override is absent,
  • implement non-stub geneva_validate_uh API,
  • implement the opt-in Section 12.5 musle_hru_event_v1 extension only after adding HRU-local peak-runoff derivation and RUSLE/Geneva same-grid factor aggregation tests,
  • evaluate whether operator tooling should auto-flag/regenerate legacy Geneva summaries that still show storm_distribution_assumption=neh4_type_b with uniform_rainfall_assumed=true and no modern hyetograph summary block,
  • evaluate refine/cleanup of route module structure (currently single geneva_bp.py),
  • address rq-engine generic payload normalization behavior that can collapse single-item arrays to scalars.

18. Open Design Decisions (Tracked)

  • Should post-fire grass/herbaceous CN augmentation become default-on in v1.1?
  • Should dual-HSG drainage policy (A/D, B/D, C/D) be handled in Geneva or remain upstream-only?
  • When should reservoir routing enter scope (v2 vs external workflow)?
  • Should we add curated panel presets beyond the full matrix (5m..24h x 1..100)?
  • What validation threshold is required before the Section 12.5 event-erosion layer can be described as more than a screening estimate for post-fire basins?

19. Wildcat5 Macro Reuse Assessment (Retained)

Direct algorithm reference candidates (port-and-test only):

  • CN transforms, weighted CN helpers, rainfall excess routines,
  • storm distribution routines,
  • UH/hydrograph routines.

Reference-only (deferred phase):

  • routing/reservoir VBA routines.

Not runtime-usable:

  • workbook sheets/forms/UI glue modules and Excel-coupled orchestration code.

20. References

  • USDA Forest Service. 2016. RMRS-GTR-334.
  • USDA NRCS. National Engineering Handbook, Part 630 (Hydrology).
  • USDA SCS. NEH Section 4 and TR-55 hydrology references.
  • USDA NRCS. 2016. Hydrology Technical Note 210-4, Hydrologic Analyses of Post-Wildfire Conditions.
  • Williams, J. R. 1975/1995. Modified Universal Soil Loss Equation family as implemented in SWAT/SWAT+ theoretical documentation.
  • U.S. Army Corps of Engineers HEC-HMS Technical Reference Manual, Modified USLE erosion method.
  • USDA NRCS. RUSLE2 Handbook, application limits for annual RUSLE2 and individual-storm interpretation.
  • USDA ARS. AnnAGNPS technical documentation, HUSLE sheet-and-rill delivery ratio procedure.
  • USDA ARS / Forest Service WEPP documentation, process-based event runoff, detachment, transport, and deposition scope.
  • Local WEPP single-storm review experience, including Scott Sheppard's investigation of kslast sensitivity and peak-flow interpretability.

Derived raster/geometry freshness

HRU GeoJSON reuse binds the selected HRU raster's verified local dependencies and legend bytes. Auto-aligned burn reuse binds the selected source's verified local dependencies and the actual canonical bound raster profile consumed by raster_stacker (grid, CRS and retained creation options, not its pixel/mask values or the driver/count/compress/nodata/dtype fields overridden by the stacker). Use the bounded GTiff/AAIGrid observer in the raster dependency freshness contract; unverified source layouts retain the same native operation uncached. Main-file mtime ordering is not content proof. Source/legend/path/profile changes reject old reuse, including restored timestamps and selection of an older source path.

New GeoJSON embeds _wepppy_freshness; new GTiff aligned burn embeds the JSON metadata tagWEPPPY_GENEVA_FRESHNESS. Each proof is an object with exactly version: 1, kind: hru_geometry | aligned_burn, attempt_id, and dependencies (the canonical JSON form of the observed identity). A null dependencies denotes newly generated unverified input, never reusable proof; missing/invalid objects are legacy/malformed and require normal rebuild. Public filenames, feature schema/envelope, nearest-neighbor alignment and explicit burn overrides are unchanged. Proofless/malformed/mismatched artifacts rebuild on the next normal request; do not invent provenance from current sources for old outputs. Archive relocation may cause conservative rebuild; no renamed user fields or NoDb migrations are required.

Use unique retainedgeneva/cache_attempts/<uuid>/ for candidates and status; attempt directories are private0700 from creation, status0600, candidates stay private until publication with the existing target mode or normal umask-derived new-file mode. Preserve ArtifactIO run-root containment, selected output symlink target, source symlink rules and the existing writer's target write authorization. Recheck the selected destination before commit. Existing artifact read/access errors propagate rather than being disguised as malformed proof or bypassed by an in-memory result. Only proven local GTiff targets may be opened for metadata inspection; unknown targets cannot trigger eager native discovery to read a tag. Native generation completes in the candidate; repeat dependency/selection checks before atomically publishing the complete GeoJSON or GTiff plus embedded proof. Reject observed drift without replacing prior accepted output. Failed candidates/status remain browsable and archived. C05 raster/legend and C06 source/effective-bound-profile observations use joint read guards across each complete set and the whole native materialization interval. Retain versions/context from the same verified acquisition separately from content identity; a changed-then-restored input cannot be accepted merely because its final bytes equal the initial bytes. Recheck current auto-discovery selection inside the publication boundary. Observed drift usesGenevaKernelError or GenevaValidationError withchanged_source, HTTP409, through the existing typed envelope. Atomic replacement is the commit point; later status-write failure is logged and cannot be reported as rollback or failure to publish. Cache hits also recheck after reading the artifact; return the validated payload instead of reopening a potentially replaced shared GeoJSON after validation. Do not present unverified layouts as coherent dependency proof. The stacker already forces GTiff output regardless of the bound input driver; retain this single-TIFF candidate publication for all native-successful inputs. An unverified bound input bypasses reuse and added profile inspection before the original native generation, without changing its accepted native format. Publication acceptance must preserve supported UID/GID and normal service-group parity as well as mode; do not infer ownership compatibility from mode bits alone.

Representative service budgets (warm-storage copied existing990-feature HRU project): full geometry query hit<=40ms settled/<=75ms cold-or-evicted; native miss added<=125ms. Auto-burn lookup hit<=30ms settled/<=40ms cold-or-evicted; native miss added<=65ms. Include final proof/access/publication checks; no settled full-payload hashes. First process initialization is reported separately; these service budgets are not end-to-end HTTP/RQ or cold-storage guarantees.

The atomic aligned-TIFF path requires a clean canonical target companion layout. Existing external masks/PAM/world/overview or other unproven target auxiliaries cannot survive unnoticed beside a newly replaced main file. Such layouts use the original native overwrite behavior uncached, with explicit attempt evidence and its preexisting weaker failure/publication guarantee; no prior-output rollback is claimed for this compatibility branch. GDAL's original overwrite can remove old auxiliaries, while main-only replacement demonstrably preserves a stale mask. Recheck clean target membership before atomic publication. This bounded exception avoids a new multi-file transaction protocol or changing accepted native input formats. After native overwrite leaves a clean target, the next normal request may establish verified embedded provenance through candidate publication; do not stamp the compatibility result with unearned strong proof.