Hydrology Disturbance Ledger Contract

Purpose

This page is the short source-of-truth contract for FEMIC P114.3 annual disturbance ledgers. It defines the schema, unit/year completeness, harvest and retention accounting, road state rules, conservation checks, CSV handoff, and recovery semantics.

The ledger is an accounting bridge from WS4/FHOPS schedules to hydrologic response. It is not a flood response or operational decision.

Quick Contract

  • Schema: femic.hydrology.disturbance.v1.

  • Grain: one row per spatial unit per year.

  • Required row completeness: every unit × every year.

  • Harvest: gross area and retention area; effective = gross - retention.

  • Roads: active, connected, built, decommissioned length and active crossings.

  • Recovery: time since last event only; no recovery curve.

  • Road actions: build, use, maintain, decommission.

  • Every row carries source event IDs.

  • No private data in tracked ledgers or fixtures.

Manifest Fields

The ledger records:

  • ledger_id, generated_utc, domain_id, years, and units;

  • a summary of unit, year, and row counts;

  • rows, caveats, and provenance.

Each unit records unit_id, area_ha, watershed_id, and optional hru_id.

Each row records:

  • year, unit_id, watershed_id, hru_id, unit_area_ha;

  • harvest_area_ha, retention_area_ha, effective_harvest_area_ha;

  • road_active_length_m, road_connected_length_m, road_built_length_m, road_decommissioned_length_m;

  • road_crossing_count;

  • years_since_harvest and years_since_road_build;

  • source_event_ids.

Road State Rules

  • A build event adds active length, connected length when the road is connected, and crossings.

  • A decommission event subtracts the same quantities.

  • use and maintain are lineage-only; they do not change state.

  • A road cannot be built while already active.

  • Decommissioning cannot exceed active length, connected length, or active crossings.

  • A road ID cannot span spatial units.

Conservation Rules

The build rejects:

  • duplicate unit, year, harvest-event, or road-event IDs;

  • unknown units;

  • event years outside the ledger;

  • non-positive harvest area or build/decommission length;

  • retention greater than harvest area;

  • total harvest greater than unit area;

  • invalid road actions and negative crossings;

  • road decommissioning beyond active state.

The validation rejects missing or duplicate unit/year rows, inconsistent effective area, negative areas or lengths, connected length above active length, and negative ages.

CSV Handoff

  • Units: unit_id, area_ha, watershed_id, hru_id.

  • Harvest: event_id, unit_id, year, area_ha, retention_area_ha, treatment, source.

  • Roads: event_id, road_id, unit_id, year, action, length_m, connected_to_stream, crossing_count, source.

The CSV loaders are the supported first handoff from WS4/FHOPS. Unknown or extra columns are ignored by the loader but should be reconciled in the source schedule.

Recovery Semantics

years_since_harvest and years_since_road_build are time counters. They do not encode hydrologic recovery, species regeneration, canopy closure, or a response curve. Those belong to P114.5/P114.7.

Cross-References