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 |
4.2 Wildcat5 Source Artifacts and Legal Posture
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.pyhsg_assignment_service.pyhru_preparation_service.pyfrequency_panel_service.pybatch_run_service.pyresults_service.pyreport_payload_service.pycn_table_service.pyartifact_io.pykernel_gateway.py
5.2 Rust (wepppyo3) kernel boundary
PyO3 adapter entrypoints:
geneva_prepare_hrusgeneva_build_frequency_panelgeneva_build_hyetographgeneva_run_batchgeneva_validate_uh(stub)
Core crate modules:
hru.rsfrequency_panel.rscn.rsuh.rsconvolution.rshyetograph.rs(selected storm-shape dispatch wired from Pythonrun_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.0and17.0 <= lat <= 72.5. - NLCD compatibility by
landuse.nlcd_db/landuse.lc_fncontainingnlcd. - HSG compatibility by
soils.ssurgo_db/soils.ssurgo_fncontainingssurgoorhydgrpdcd.
6.3 Enablement semantics
Current behavior is membership-driven:
- Geneva is auto-enabled on initialization.
set_enabled(false)does not disable runtime execution; effectiveenabledremainstrue.- 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(default0.20)uh_method:scs_triangular | scs_curvilinear(defaultscs_triangular)default_hsg_code:1 | 2 | 3 | 4 | null(integer or null only)unresolved_hsg_policy:error | assume_d(defaultassume_d)strict_burn_nodata: boolean (defaultfalse)allow_cross_hsg_merge: boolean (defaultfalse)hydrophobic_forest_high: boolean (defaulttrue)hydrophobic_forest_moderate: boolean (defaultfalse)hydrophobic_shrub_high: boolean (defaulttrue)hydrophobic_shrub_moderate: boolean (defaultfalse)min_hru_area_ha: numeric>= 2.0(default2.0)
Validation highlights:
- boolean fields reject string booleans,
default_hsg_coderejects string numerals,min_hru_area_ha < 2.0is 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_tiflanduse_tifhydgrpdcd_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, thendisturbed_cropped), - auto-discovered Disturbed burn refs are materialized as
geneva/inputs/burn_severity_4class.tifon the canonicalbound.tifgrid with nearest-neighbor reprojection before the kernel request, - explicit
burn_severity_tifoverrides 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_classnlcd_labelhsgburn_severityhydrophobiccn_arc_iiantecedent_condition_sourcesourcenotes
Migration behavior:
- legacy files missing
antecedent_condition_sourceare migrated to schema v1 with defaultarc_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-Sha256header token.
8.3 Runtime CN-table consumption
cn_table.csv is the active runtime source for persisted HRU CN values.
GenevaHruPreparationServiceresolves HRUcn_arc_iiby exact lookup on:nlcd_classhsgburn_severityhydrophobic
- The resolved CN is written into
geneva/hru_table.parquet, and downstreamrun_batchuses that persisted parquet. - Editing
geneva/data/cn_table.csvdoes not retroactively mutate an existinghru_table.parquet; rerunprepare_hrusto regenerate the artifact. prepare_hrusnow invalidates its cached summary when the CN-table hash changes, so rerunning the task after a CN-table edit refresheshru_table.parqueteven whenforce_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, optionalburn_severity_tif) default_hsg_code(user override only)default_hsg_derivation(currentlyuser_overrideor null)unresolved_hsg_policystrict_burn_nodataallow_cross_hsg_mergemin_hru_area_ha- hydrophobic toggles
9.2 HRU key and burn/hydrophobic rules
Kernel HRU key dimensions:
landuse_classhsg_groupburn_severity_classhydrophobic_classis_water
Burn mapping:
0 -> unburned1 -> low2 -> moderate3 -> high- nodata in-bound:
- error when
strict_burn_nodata=true, - mapped to
unburnedwith warning otherwise.
- error when
Hydrophobic toggles:
- forest classes
41,42,43use forest toggles for moderate/high burn, - shrub class
52uses 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->D0or nodata => unresolved5/6/7and other unexpected codes => warning + unresolved path
Fallback chain:
- coded lookup
default_hsg_code(if provided)- unresolved policy:
error=> failassume_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
hsgunlessallow_cross_hsg_merge=true
Recipient selection order:
- smallest
abs(delta_cn_arc_ii) - largest recipient area
- 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_hrusreplaces 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, else75) - HSG adjustment (
A=0,B=+7,C=+14,D=+21) - burn adjustment (
unburned=0,low=+2,moderate=+5,high=+8) - hydrophobic adjustment (
+6whenhydrophobic_class=true) - final clamp:
[30, 100] cn_lambda_005derived with RMRS-style transform and cap behavior forcn_arc_ii > 98.5.
9.6 HRU outputs and persisted artifacts
Persisted artifacts:
geneva/hru_table.parquetgeneva/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
GenevaHruPreparationServicepasses kernel output paths (hru_map_output_tif,hru_map_legend_output_json) and validates artifact materialization plus returnedhru_mapsummary metadata.
Persisted columns:
hru_idarea_m2area_acarea_fractionlanduse_classhsg_groupburn_severity_classhydrophobic_classis_watercn_arc_iicn_lambda_020cn_lambda_005antecedent_condition_sourcecn_sourcehsg_sourcecollapsed_from_hru_idswarnings
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
artifactsincludehru_map_relpathandhru_map_legend_relpath. - current summary
hru_mapblock includes:nodata_valuehru_value_countfallback_id_match_countmapping_status(complete|partial)active_cell_count,mapped_cell_count,unmapped_cell_countunresolved_component_countand boundedunresolved_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_ballow_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), and60-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 withStorm 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
0intensities 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_unavailableinstead 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_typematches persisted panel distribution; otherwise panel is rebuilt - cell
availabilityisavailable|unavailable reason_codemust be null when available- unavailable reason codes are:
duration_unavailableari_unavailablesource_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_idsoptional list ofcligen_freq|noaa14_pdsevent_filter.durations_minutesoptional positive int listevent_filter.ari_yearsoptional positive int listhyetograph.distribution_typemust be one of:uniformneh4_type_btype_itype_iatype_iitype_iii
hyetograph.time_step_minutes > 0hyetograph.time_step_minutesmust evenly divide each selected storm duration for runtime CN/hydrograph convolution (non-divisible combinations are rejected asinvalid_inputbefore kernel run-batch execution)hyetograph.distribution_typemust match the persisted frequency-paneldistribution_type; callers must rebuild panel first when switching storm shape- exactly one of:
runoff_model.tc_hours, orrunoff_model.timing_method(kirpich|kent|simas)
Prerequisites:
geneva/frequency_panel.jsonmust existgeneva/hru_table.parquetmust 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_minutesanddepth_mm - uses request
hyetograph.distribution_type+time_step_minutes - dispatches by closed storm-shape enum:
uniform: linear cumulative rainfall from0to duration depthneh4_type_b: legacy Geneva Type B curvetype_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.jsongeneva/storms/<storm_id>/hyetograph.parquetgeneva/storms/<storm_id>/summary.jsongeneva/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_hourstime_minutes,cumulative_rainfall_mm- HRU rows (
hru_id,area_m2,cn_lambda_020)
Kernel computes:
- CN excess (
0.20and0.05forms 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.parquetgeneva/storms/<storm_id>/excess_hyetograph.parquetgeneva/storms/<storm_id>/hydrograph.parquetgeneva/storms/<storm_id>/summary.json
Batch-level:
geneva/storm_inputs.jsongeneva/batch_summary.json
Run status aggregation:
failedif any available storm fails- else
completed_with_gapsif 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
- raw WinTR-20 distribution output:
- 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:
- Treat the 24-hour table as a piecewise-linear cumulative mass curve
F(t)over0 <= t <= 24hours. - Validate
0 < duration_minutes <= 1440,depth_mm > 0, andtime_step_minutes > 0. - Convert event duration to hours,
d = duration_minutes / 60. - For
d == 24, use the full source curve. - For
d < 24, find the window startain[0, 24 - d]that maximizesF(a + d) - F(a). - Candidate starts must include source table times and source table times minus
d, clipped to[0, 24 - d]. - If candidates tie within tolerance, choose the candidate closest to
12 - d / 2; if still tied, choose the earliest. - Let
r = F(a + d) - F(a). Fail ifr <= 0. - Build the output time vector with
0and exactduration_minutesendpoints. Intermediate points are regulartime_step_minutesmultiples strictly inside the duration; iftime_step_minutes >= duration_minutes, output only the two endpoints. If duration is not evenly divisible by the step, the final interval is shorter. - For output time
tin the event, computeevent_fraction(t) = (F(a + t_hours) - F(a)) / r. - Force the first and final output points to
0.0and1.0, enforce monotonicity within tolerance, and setcumulative_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_typesource_curve_duration_hours=24extraction_start_hoursextraction_end_hoursextraction_ratio_to_24hevent_depth_is_duration_depth=truesource_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
idlepreparedrunningcompletedcompleted_with_gapsfailed
12.2 Status and results payloads
status_payload includes:
status,status_messageprogress(completed,total,unit,percent,updated_at)active_job_id,last_job_id
results_payload includes:
statuslast_prepare_summarylast_run_summarywarnings,errors
state_payload additionally includes:
state_version=1enabledconfig_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_availabilityari_yearsmeasures = [peak_discharge, runoff_depth, runoff_volume]duration_minutes
chartgrouped by ARI, marker-labeled by durationevent_tablewith status and metricsselected_storm_idsync key- sanitized
warningsanderrors
Current row status resolution precedence:
- panel availability (
unavailableif not available), - run summary failed/completed sets,
- 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_idfromhru_table.parquet - raster-value join key:
hru_valuefromhru_map_legend.jsonrows[*].hru_value - canonical crosswalk:
hru_map_legend.jsonrows[*]whererows[*].hru_id <-> rows[*].hru_value
Required join behavior for query/report consumers:
- Join event rows to HRU measure rows on
storm_id. - Join HRU measure rows to HRU attributes/geometry on
hru_id. - 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 value1) - 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_batchhru_excess[].peak_runoff_m3_s - computation path: per-HRU
incremental_excess_mmconvolved with the selected Geneva unit hydrograph and that HRU'sarea_m2 - prohibited shortcut: do not area-split watershed
summary_metrics.peak_dischargeto 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_dischargemust fail validation with explicit scope error codeunsupported_measure_scope.
12.4.5 Query response envelope for HRU map rows (WP02)
HRU map row queries return an additive contract envelope:
schema_version(current1)filters(storm_id,measure_id)availability:status = available | unavailablereason_code(legacy_hru_event_measures_missingwhen unavailable)artifact_path(canonicalgeneva/hru_event_measure_rows.parquet)
query(query-engine style payload used for retrieval)records(row list; empty when unavailable)schema(present wheninclude_schema=true; otherwisenull)row_countwarnings,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=unavailablewith 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(current1)availability:status = available | unavailablereason_code:hru_map_missingwhengeneva/hru_map.tifis absenthru_map_legend_missingwhengeneva/hru_map_legend.jsonis absent
artifact_path
join_keys:primary = hru_valuesecondary = hru_id
feature_collection(GeoJSONFeatureCollection, WGS84)feature_countbounds_wgs84([min_x, min_y, max_x, max_y]ornull)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 Araster. - 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
kslastand 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 finalhru_excess[].cumulative_excess_mmvalue.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, andP: gridded RUSLE factor rasters from the same project.cfrg_factor: coarse-fragment factor; fixed to1.0in 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.parquetgeneva/hru_map.tifgeneva/hru_map_legend.jsongeneva/hru_event_measure_rows.parquetgeneva/batch_summary.json- completed per-storm
hru_excessrows, 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.tifrusle/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_sby 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, selectedk, selectedc, andpmust 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_productas the area-weighted mean ofK * LS * C * P, not asmean(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 usefactor_productin the equation. - Persist
valid_factor_area_fraction; HRUs below a configured validity threshold are unavailable withreason_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_batchemitshru_excess[].peak_runoff_m3_sandhru_excess[].time_to_peak_minutes. peak_runoff_m3_sis 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.parquetmaterializes this asmeasure_id=hru_peak_runoff,unit=m3_s.
- Rust
- Erosion extension requirement:
- Treat this HRU-local value as
qpeak_m3_sinput formusle_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.
- Treat this HRU-local value as
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.parquetgeneva/hru_map.tifgeneva/hru_map_legend.jsongeneva/hru_event_measure_rows.parquetgeneva/batch_summary.jsonrusle/manifest.json- selected RUSLE
K,LS,C, orPrasters
- 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/hafor intensity-style choropleths andtfor 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 * Pproduct 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/configPOST /runs/<runid>/<config>/api/geneva/configPOST /runs/<runid>/<config>/tasks/geneva/prepare_hrusPOST /runs/<runid>/<config>/tasks/geneva/build_frequency_panelPOST /runs/<runid>/<config>/tasks/geneva/run_batch
Status/results/query/report:
GET /runs/<runid>/<config>/api/geneva/statusGET /runs/<runid>/<config>/api/geneva/resultsGET /runs/<runid>/<config>/api/geneva/frequency_panelGET /runs/<runid>/<config>/query/geneva/summaryPOST /runs/<runid>/<config>/query/geneva/hru_map_rowsPOST /runs/<runid>/<config>/query/geneva/hru_map_featuresGET /runs/<runid>/<config>/report/geneva/summary
CN-table routes:
GET /runs/<runid>/<config>/modify_geneva_cn_tableGET /runs/<runid>/<config>/api/geneva/cn_table_metaGET /runs/<runid>/<config>/api/geneva/cn_table_snapshotPOST /runs/<runid>/<config>/tasks/modify_geneva_cn_tablePOST /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_rowsreturns top-levelavailability + filters + recordspayload (not wrapped),POST /query/geneva/hru_map_featuresreturns top-levelavailability + feature_collectionpayload (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-hrusPOST /api/runs/{runid}/{config}/geneva/build-frequency-panelPOST /api/runs/{runid}/{config}/geneva/run-batchPOST /api/runs/{runid}/{config}/geneva/run-workflow
State route:
GET /api/runs/{runid}/{config}/geneva/state
Workflow chaining:
run-workflowenqueues prepare -> panel -> run-batch dependencies,- workflow normalization forces:
prepare.force_rebuild = truepanel.rebuild = true
State response extras:
contract_versiondeployment_revisionrun_state_domainrun_state_revisionrun_state_vectoretag- plus Geneva
state_payloadfields
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.csvdata/cn_table_audit.jsonlhru_table.parquethru_prepare_summary.jsonfrequency_panel.jsonstorm_inputs.jsonbatch_summary.jsonhru_event_measure_rows.parquetstorms/<storm_id>/hyetograph.parquetstorms/<storm_id>/excess_hyetograph.parquetstorms/<storm_id>/hydrograph.parquetstorms/<storm_id>/summary.json- optional normalization artifact:
normalized_sources/wepp_cli_pds_mean_metric_kernel.csvnormalized_sources/atlas14_intensity_pds_mean_metric_kernel.csv
WP02 production note:
hru_event_measure_rows.parquetis materialized duringrun_batchfrom completed stormhru_excessrows 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.parquethru_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 batchvalidation), - 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.pytests/weppcloud/routes/test_geneva_wp08_routes.pytests/rq/test_geneva_rq.pytests/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_codewhen user override is absent, - implement non-stub
geneva_validate_uhAPI, - implement the opt-in Section 12.5
musle_hru_event_v1extension 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_bwithuniform_rainfall_assumed=trueand no modernhyetographsummary 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..24hx1..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
kslastsensitivity 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.