# 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.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 | noaa14_pds`; copied from panel cell. |
| `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 | runoff_volume | hru_peak_runoff` only. |
| `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:

```text
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 | noaa14_pds`; copied from the panel cell. |
| `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:

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

Canonical enqueue success shape (single-job endpoints):

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

Workflow enqueue success shape:

```json
{
  "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 tag`WEPPPY_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 retained`geneva/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 uses`GenevaKernelError` or
`GenevaValidationError` with`changed_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.
