FEMIC Hydrology Response Bundles
WS4 consumes versioned FEMIC hydrology response bundles for screening-only spatial scheduling. It does not run FEMIC discovery, frequency fitting, surrogate training, or flood-risk calculation.
This page covers the read-only consumer contract implemented across P57, P60, and P62. It covers bundle validation, registration, mapping, readiness, and preflight; the actual flood model remains a producer-side input.
Bundle Contract
A FEMIC response bundle contains manifest.json, artifacts/<role>/, and
provenance/response_plan.json. WS4 validates and pins:
bundle_idandbundle_version;the manifest SHA-256;
every artifact role, schema, media type, size, and SHA-256;
the response-surface and flood-risk summaries;
the domain and disturbance-ledger identifiers; and
the producer applicability domain, uncertainty, caveats, and consumer contract.
Required artifact roles are response_surface, flood_risk, domain,
and disturbance_ledger. Optional roles include the surrogate model and
validation artifacts, frequency fits, Tier 0 screening, benchmark checks, and
the validation report, model card, and pilot run.
ws4.io.hydrology.load_femic_hydrology_bundle raises on an invalid bundle.
validate_femic_hydrology_bundle returns a report with specific errors.
bundle_pin returns the stable downstream pin. The module uses only the
standard library and never contacts FEMIC or the network.
Python Usage
from pathlib import Path
from ws4.io.hydrology import (
bundle_pin,
load_femic_hydrology_bundle,
read_femic_flood_risk,
validate_femic_hydrology_bundle,
)
bundle_path = Path("data/femic/hydrology-response-2026.10.0")
report = validate_femic_hydrology_bundle(bundle_path)
if not report.is_valid:
raise RuntimeError("; ".join(report.errors))
bundle = load_femic_hydrology_bundle(
bundle_path,
expected_bundle_id="hydro-response-example",
expected_bundle_version="2026.10.0",
)
pin = bundle_pin(bundle)
risk = read_femic_flood_risk(bundle)
print(pin["manifest_sha256"])
for row in risk.rows:
print(row.receptor_id, row.return_period, row.ratio)
Validation Rules
The validator rejects:
a wrong manifest or artifact schema;
an absolute artifact path, a
..traversal, or a path outside the bundle;a missing, duplicate, or unknown required role;
a size or SHA-256 mismatch;
a response-surface ID, baseline, or return-period mismatch;
a flood-risk source-surface, table-ID, baseline, row-count, or row-ratio mismatch;
a domain or disturbance-ledger ID mismatch; and
a malformed consumer contract.
The validator reports warnings for unknown optional roles. It does not infer missing watersheds from block IDs, does not repair a producer bundle, and does not turn a valid checksum into a hydrologic claim.
Registration
Register a validated bundle in a compiled dataset:
ws4 hydrology register \
--dataset build/compiled \
--bundle data/femic/hydrology-response-2026.10.0 \
--bundle-id hydro-response-example \
--bundle-version 2026.10.0
Registration writes the pin to manifest.json under
metadata.hydrology_products and to a hydrology_products.json sidecar.
The bundle is referenced, not copied. A bundle inside the dataset is stored as a
relative path; an external bundle keeps its absolute path. Do not copy a private
bundle into a tracked dataset.
Inspect and validate the registered pin:
ws4 hydrology inspect --dataset build/compiled --json
ws4 hydrology validate --dataset build/compiled
Revalidation checks the registered bundle_id, bundle_version, manifest
SHA-256, and every artifact size/checksum. A changed bundle manifest fails even
if its schema still parses.
CLI
Direct bundle inspection and validation remain available:
ws4 hydrology validate data/femic/hydrology-response-2026.10.0
ws4 hydrology validate data/femic/hydrology-response-2026.10.0 \
--bundle-id hydro-response-example \
--bundle-version 2026.10.0
ws4 hydrology inspect data/femic/hydrology-response-2026.10.0 --json
ws4 hydrology map --dataset build/compiled --crosswalk crosswalk.csv \
--out build/hydrology_mapping
ws4 hydrology screen --dataset build/compiled \
--mapping build/hydrology_mapping --schedule schedule.csv \
--out build/hydrology_screen
ws4 hydrology screen --dataset build/compiled \
--mapping build/hydrology_mapping --schedule schedule.csv \
--exposure schedule-exposure.json --out build/hydrology_screen
validate emits a deterministic JSON report by default and exits non-zero on
an invalid bundle. inspect prints the bundle pin and artifact roles for a
valid bundle; an invalid bundle prints the validation report and exits non-zero.
Pass exactly one of a direct BUNDLE argument or --dataset.
Preflight
ws4 hydrology preflight combines the bundle pin, readiness evidence, crosswalk review state, and mapping coverage into one fail-closed report. It is orchestration over the existing validators; it does not run a schedule, write files, or contact the network.
ws4 hydrology preflight \
--dataset build/compiled \
--crosswalk reviewed-crosswalk.csv \
--metadata reviewed-crosswalk.meta.json \
--policy require_reviewed \
--json
The default preflight policy is require_reviewed. The report sets
screening_ready to true only when:
the bundle is structurally valid;
the readiness state is allowed by the policy;
a crosswalk was supplied;
the crosswalk is reviewed under the selected policy; and
every fragment and block is mapped.
A missing crosswalk is always a blocking reason, so a direct-bundle preflight
can report readiness evidence but cannot declare screening safe. Partial
mapping is available with --allow-partial for diagnosis, but unmapped
fragments or blocks still block readiness.
The command exits non-zero when screening_ready is false. A structurally
valid bundle is not a hydrologically reviewed bundle, and a ready preflight is
not a hydrologist review or a regulatory flood map.
Road and Culvert Exposure
The exposure table is an explicit, schedule-bound input:
{
"schema_version": "ws4.hydrology.exposure.v1",
"exposure_id": "exposure-2026-001",
"generated_utc": "2026-10-26T00:00:00+00:00",
"source_id": "reviewed-road-and-culvert-inventory",
"review_status": "reviewed",
"reviewer_id": "reviewer-id",
"schedule_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"watershed_ids": ["watershed-1"],
"periods": [0, 1],
"rows": [
{
"watershed_id": "watershed-1",
"period": 0,
"road_built_km": 0.0,
"road_used_km": 1.25,
"road_decommissioned_km": 0.0,
"culvert_count": 4,
"culvert_exposed_count": 1
},
{
"watershed_id": "watershed-1",
"period": 1,
"road_built_km": 0.5,
"road_used_km": 1.75,
"road_decommissioned_km": 0.0,
"culvert_count": 4,
"culvert_exposed_count": 2
}
],
"caveats": ["Screening input only."]
}
watershed_ids and periods declare the complete grid. Every declared watershed/period pair must have exactly one row; a missing row is an error, not a zero. Lengths are finite non-negative numbers, counts are non-negative integers, reviewed metadata requires reviewer_id, and schedule_sha256 must be a 64-character hex digest.
The table is bound to one schedule hash. Reusing it for a different schedule is a refusal in the screening path, not a fallback. WS4 does not buffer roads, match culverts to streams, assign a watershed to a road, or infer missing periods. There is no geometry in this contract.
Load it with ws4.io.hydrology_exposure.load_hydrology_exposure. The
returned object preserves the file SHA-256, source, review state, declared
watersheds and periods, and the canonical feature values for a watershed and
period.
Screening With Exposure
hydrology screen –exposure checks the table’s schedule hash against the schedule before reading response scenarios. A mismatch refuses. For each mapped watershed and period, the screen adds the raw exposure features and these calculated densities using the FEMIC watershed area:
road_built_density_km_per_km2;road_used_density_km_per_km2;road_decommissioned_density_km_per_km2;culvert_exposure_per_km2.
A global covariate may not duplicate an exposure feature. A missing declared
watershed/period is a refusal, not a zero. The screen manifest records the
exposure ID, file digest, review state, and coverage.exposure_used. The row
CSV carries the raw features and derived densities. If no response-surface
scenario names an exposure feature, the result carries a warning that exposure
was supplied but not used.
The optimizer does not accept exposure yet. A flood-screen config that names
exposure or exposure_path is refused until exposure can be derived for
each candidate schedule. A fixed table bound to one schedule is not a valid
optimizer input.
Validation Evidence
P60.1 reads the optional FEMIC validation-report and model-card artifacts. The readiness command is a report, not a gate:
ws4 hydrology readiness data/femic/hydrology-response-2026.10.0 --json
ws4 hydrology readiness --dataset build/compiled --json
Statuses:
not_available: no validation report or model card is packaged.provisional: evidence exists but the model card is not reviewed.conditionally_ready: reviewed with conditions.ready: reviewed, with a recorded hydrologist review and no tail-check failures.blocked: a tail-check failure is recorded.
The report carries the producer validation/model-card IDs, review status, usable fits, tail-check failures, benchmark pass/fail/not-evaluated counts, full-pilot readiness, and a deterministic evidence digest. Missing evidence is reported as missing; it is never treated as approval. The P60.1 command does not refuse screening or optimization; a later policy task decides how the evidence gates use.
Readiness Policies
P60.2 gates use on the readiness report:
allow_provisional(default): allow missing/provisional evidence with the recorded warnings, but a tail-check block still refuses.require_reviewed: allowreadyorconditionally_readyonly.require_ready: allowreadyonly.
A tail-check block refuses under every policy. The only override is
--allow-tail-failures with allow_provisional; it is an explicit risk
acceptance, not a claim that the fit is safe.
ws4 hydrology screen ... --readiness-policy require_reviewed
ws4 hydrology screen ... --allow-tail-failures
The flood-screen config accepts the same policy:
{
"schema_version": "ws4.hydrology.flood_screen.v1",
"mapping": "build/hydrology_mapping",
"covariates": {},
"scenario_tolerance": 0.05,
"refusal_penalty": 1000000000000.0,
"readiness_policy": "require_reviewed",
"allow_tail_failures": false
}
FloodRiskModel enforces the policy when it is constructed, so an optimizer
run with disallowed evidence fails early with a clear message instead of
returning refusal penalties for every schedule.
Mapping WS4 Support
Mapping requires an explicit, reviewed crosswalk. WS4 never infers a watershed from a block ID, a centroid, or a nearest-neighbor join. The crosswalk CSV has exactly one support key per row:
fragment_id,block_id,unit_id,watershed_id,receptor_id,notes
1,,unit-1,watershed-1,receptor-1,fragment-level review
2,,unit-1,watershed-1,receptor-1,fragment-level review
,11,unit-2,watershed-2,receptor-2,block-level review
A block-level row expands to every fragment in that block. A block mapping can
also be derived from complete, consistent fragment rows. Fragments in one block
must agree on unit_id, watershed_id, and receptor_id or mapping
fails.
Optional review metadata records the crosswalk identity and review state:
{
"schema_version": "ws4.hydrology.crosswalk.v1",
"crosswalk_id": "crosswalk-example",
"created_utc": "2026-10-26T00:00:00+00:00",
"review_status": "reviewed",
"reviewed_by": "reviewer-id",
"method": "Manual fragment/block review against FEMIC units",
"source": "Reviewed public domain bundle",
"caveats": ["Screening crosswalk only."]
}
The optional crosswalk_sha256 field pins the CSV. Missing metadata is
recorded as not_reviewed with a warning; it is never silently treated as
reviewed.
Run the mapping:
ws4 hydrology map \
--dataset build/compiled \
--crosswalk reviewed-crosswalk.csv \
--metadata reviewed-crosswalk.meta.json \
--out build/hydrology_mapping
The command writes hydrology_fragments.csv, hydrology_blocks.csv, and
hydrology_mapping.json. The manifest records the FEMIC bundle pin, crosswalk
checksum, review status, coverage, warnings, and caveats. A crosswalk that does
not cover every fragment and block fails unless --allow-partial is set; a
partial mapping records the unmapped IDs.
No spatial inference or FEMIC re-run is performed.
Schedule Screening
P57.4 screens a WS4 schedule against the pinned response surface and flood-risk rows. It is read-only: no simulator, optimizer, objective, or FEMIC process is run.
ws4 hydrology screen \
--dataset build/compiled \
--mapping build/hydrology_mapping \
--schedule schedule.csv \
--out build/hydrology_screen
The screen:
sums cumulative block area by mapped watershed and schedule period;
derives
harvest_fractionfrom the FEMIC domain watershed area;adds optional global covariates from
--covariates features.json;selects the nearest response-surface scenario within
--scenario-tolerance(default0.05);joins the selected response ratio to flood-risk rows by watershed, receptor, and return period; and
writes
hydrology_screen.csvand a deterministichydrology_screen.jsonmanifest.
A missing scenario feature, a harvest fraction outside the tolerance, a
missing watershed area, or no flood-risk row is a refusal. Refusals fail the
command by default. --allow-refused writes the inside-domain rows and records
the refusals in the manifest.
The screening peak flow is baseline_peak_flow_m3s * response_ratio. The
bundle’s own scenario flow, exceedance probability, and expected annual damage
are carried alongside it and are not recomputed. The row is a planning screen,
not a schedule-specific process simulation or regulatory flood map.
Flood Accounts In Optimization
P57.5 can expose the screening rows as optional flood.* accounts to the optimizer objective. It does not change the simulator or write flood accounts from ws4 simulate.
Create a flood-screen config:
{
"schema_version": "ws4.hydrology.flood_screen.v1",
"mapping": "build/hydrology_mapping",
"covariates": {},
"scenario_tolerance": 0.05,
"refusal_penalty": 1000000000000.0
}
Pass it to ws4 optimize (or watch/calibrate):
ws4 optimize \
--dataset build/compiled \
--targets targets.yaml \
--flood-screen-config flood-screen.json \
--out build/run
Targets use the account names:
flood.<receptor_id>.<return_period>.ratio
flood.<receptor_id>.<return_period>.peak_flow_m3s
flood.<receptor_id>.<return_period>.exceedance_probability
flood.<receptor_id>.<return_period>.expected_annual_damage
For example:
targets:
- account: flood.receptor-1.100.ratio
period: 1
maximum: 1.10
max_weight: 10000
A schedule outside the response-surface tolerance is not extrapolated. The optimizer returns the configured refusal_penalty for that evaluation. When a flood-screen config is active, the move-based delta evaluator is disabled and whole-schedule evaluation is used; this is a deliberate screening-first boundary, not a performance claim.
Flood-Risk Table
Each row records a receptor, watershed, return period, baseline and scenario peak flow in cubic metres per second, the scenario/baseline ratio, and optional exceedance probability and expected annual damage. The table is a decision-support screening surface. It is not a regulatory flood map, design flood, or operational safety determination.
Producer Phase Labels
FEMIC records producer-side workstream labels in
consumer_contract.consumer_phases (currently ws4: P49 and
fhops: P14). Those are not WS4 or FHOPS phase numbers. WS4’s hydrology
consumer phase is P57, and FHOPS has its own phase numbering. Preserve the
labels as producer metadata; do not rewrite the manifest.
Boundary
Use only a pinned, validated bundle.
Registration references the bundle; it does not copy, download, or re-run FEMIC.
Preserve the producer CRS, units, return periods, caveats, and provenance.
Refuse queries outside the recorded applicability domain.
Do not use the bundle as a regulatory flood map or design-flood service.
The FEMIC P114.9 handoff is conditional on hydrologist review and a completed process-model pilot. A valid bundle is internally consistent, not hydrologically validated.
See Also
The FEMIC producer contract in the FEMIC repository:
docs/reference/contracts/hydrology-response-bundles.rst.
Verification
The P62 integration fixture is tests/test_hydrology_integration.py. It runs validate, readiness, preflight, map, and screen over a synthetic bundle, dataset, crosswalk, exposure table, and schedule. It also checks the fail-closed cases: tail-check block, unreviewed crosswalk, partial mapping, missing required exposure features, schedule-hash mismatch, and optimizer exposure refusal.
The fixture is synthetic. It is not a real watershed, road inventory, culvert dataset, flood map, or regulatory result.