Hydrology Response Bundles

Purpose

P114.8 packages the outputs of the hydrology ladder into one pinned consumer artifact. WS4 and FHOPS should read this bundle instead of re-running FEMIC domain discovery, frequency fitting, or surrogate training.

A response bundle contains:

  • a return-period response surface;

  • a receptor-level flood-risk table;

  • optional surrogate model, validation, frequency, screening, pilot, and model-card artifacts;

  • the hydrology domain and disturbance-ledger provenance digests; and

  • a manifest with deterministic identity, checksums, applicability domain, uncertainty, caveats, and a consumer contract.

The response manifest uses femic.hydrology.response.v1. The flood-risk table uses femic.hydrology.flood_risk.v1. The build plan uses femic.hydrology.response_plan.v1.

This is a planning and screening surface, not a regulatory flood map or a design-flood service.

Bundle Layout

hydrology-response-<bundle-id>-<version>/
  manifest.json
  artifacts/
    response_surface/response_surface.json
    flood_risk/flood_risk.json
    surrogate_model/surrogate_model.json
    surrogate_validation/surrogate_validation.json
    frequency_fit/frequency_fit.json
    frequency_pairing/frequency_pairing.json
    tier0_screening/screening.json
    domain/domain.json
    disturbance_ledger/disturbance.json
    benchmark_check/benchmark.json
    validation_report/validation_report.json
    model_card/model_card.json
    pilot_run/pilot_run.json
  provenance/
    response_plan.json

Artifact paths are relative to the bundle root. The manifest records the media type, schema, size, and SHA-256 of every file.

Build A Bundle

Write a plan that names local JSON artifacts:

{
  "schema_version": "femic.hydrology.response_plan.v1",
  "bundle_version": "2026.10.0",
  "domain_id": "fixture-domain",
  "ledger_id": "fixture-ledger",
  "response_surface_id": "fixture-surface",
  "artifacts": [
    {
      "role": "response_surface",
      "path": "response_surface.json",
      "schema_version": "femic.hydrology.flood_response.v1"
    },
    {
      "role": "flood_risk",
      "path": "flood_risk.json",
      "schema_version": "femic.hydrology.flood_risk.v1"
    },
    {
      "role": "domain",
      "path": "domain.json",
      "schema_version": "femic.hydrology.domain.v1"
    },
    {
      "role": "disturbance_ledger",
      "path": "disturbance.json",
      "schema_version": "femic.hydrology.disturbance.v1"
    }
  ],
  "applicability_domain": {
    "feature_names": ["harvest_fraction"],
    "min_values": {"harvest_fraction": 0.0},
    "max_values": {"harvest_fraction": 0.6},
    "mean_values": {"harvest_fraction": 0.3},
    "scale_values": {"harvest_fraction": 0.2},
    "max_distance": 3.0
  },
  "uncertainty": {"interval": "95%", "basis": "surrogate held-out"},
  "caveats": ["Screening only; hydrologist review required."]
}

Build and inspect from Python:

from pathlib import Path
from femic.hydrology.response_bundle import (
    audit_hydrology_response_bundle,
    build_hydrology_response_bundle,
)

result = build_hydrology_response_bundle(
    Path("plan.json"),
    Path("bundles/hydrology-response-2026.10.0"),
)
audit = audit_hydrology_response_bundle(result.bundle_dir)
print(result.manifest.bundle_id, audit.is_valid)

Build and inspect from the CLI:

python -m femic hydrology bundle \
  --plan plan.json \
  --output-dir bundles/hydrology-response-2026.10.0

python -m femic hydrology inspect \
  bundles/hydrology-response-2026.10.0 --json

Use --overwrite only to replace an existing FEMIC response bundle. The builder refuses to overwrite an arbitrary directory.

Flood-Risk Table

The flood-risk table records one row per receptor and return period:

from femic.hydrology.response_bundle import (
    FloodRiskRow,
    build_flood_risk_table,
    write_flood_risk_table,
)

table = build_flood_risk_table(
    (
        FloodRiskRow(
            receptor_id="receptor-1",
            watershed_id="watershed-1",
            return_period=100.0,
            baseline_peak_flow_m3s=120.0,
            scenario_peak_flow_m3s=150.0,
            ratio=1.25,
            expected_annual_damage=42000.0,
        ),
    ),
    source_surface_id="fixture-surface",
    baseline_name="baseline",
)
write_flood_risk_table(table, Path("flood_risk.json"))

Ratios must equal scenario flow divided by baseline flow. Return periods must be greater than one year. Flows must be positive and finite.

Pinning And Consumer Read Order

Consumers must:

  1. Pin bundle_id and bundle_version from manifest.json.

  2. Verify every artifact SHA-256 before use.

  3. Read the response surface and flood-risk table before optional artifacts.

  4. Check the query against applicability_domain and refuse unsupported queries unless a reviewed extrapolation is approved.

  5. Preserve the recorded CRS, units, return periods, and caveats.

Recommended read order:

manifest.json
artifacts/response_surface/*.json
artifacts/flood_risk/*.json
artifacts/surrogate_model/*.json
artifacts/domain/*.json
artifacts/disturbance_ledger/*.json
artifacts/validation_report/*.json
artifacts/model_card/*.json

WS4 P49 consumes the response surface and flood-risk table as landscape-level schedule constraints and screening objectives. FHOPS P14 consumes the same bundle for operational road and harvest integration. Neither consumer should re-run FEMIC discovery or hydrology to use a pinned bundle.

Determinism And Audit

bundle_id is derived from the canonical plan and artifact checksums. Given the same plan and input bytes, the identity is stable. generated_utc can be overridden for reproducible fixtures.

audit_hydrology_response_bundle validates the manifest schema, required roles, consumer contract, artifact paths, sizes, and checksums.

Limits

  • A valid bundle is internally consistent, not hydrologically correct.

  • The bundle does not establish public-gauge calibration.

  • Applicability domains are model-specific and may be empty when no surrogate is packaged.

  • Flood-risk rows are decision-support screening values, not regulatory floodplain mapping.

  • Hydrologist review is required before operational use.

See Also