Hydrology Response Bundle Contract
Purpose
This page is the source-of-truth contract for FEMIC P114.8 response and flood-risk packaging. It defines bundle identity, layout, manifest fields, checksums, applicability, pinning, and the WS4/FHOPS read handshake.
Quick Contract
Response manifest schema:
femic.hydrology.response.v1.Flood-risk schema:
femic.hydrology.flood_risk.v1.Build-plan schema:
femic.hydrology.response_plan.v1.Manifest name:
manifest.json.Artifact root:
artifacts/<role>/.Provenance root:
provenance/.Required roles:
response_surface,flood_risk,domain,disturbance_ledger.Optional roles:
surrogate_model,surrogate_validation,frequency_fit,frequency_pairing,tier0_screening,benchmark_check,validation_report,model_card,pilot_run.Every artifact records schema, media type, size, and SHA-256.
Consumers pin
bundle_idandbundle_versionand verify checksums.Tracked fixtures must use public or synthetic data only. No private, Indigenous, or licence-restricted data belongs in a tracked bundle.
This is not a regulatory flood map or a design-flood service.
Plan Contract
A plan is a JSON object with:
schema_versionequal tofemic.hydrology.response_plan.v1;non-empty
bundle_version,domain_id,ledger_id, andresponse_surface_id;a non-empty
artifactslist;optional
applicability_domainanduncertaintyobjects;optional
caveatsandprovenanceobjects.
Each artifact entry records role, relative path, optional
schema_version, and optional description. Roles are unique within a
plan. Paths are resolved relative to the plan file.
Artifact schema expectations:
response_surfacefemic.hydrology.flood_response.v1flood_riskfemic.hydrology.flood_risk.v1surrogate_modelfemic.hydrology.surrogate_model.v1frequency_fitfemic.hydrology.flood_frequency.v1tier0_screeningfemic.hydrology.screening.v1domainfemic.hydrology.domain.v1disturbance_ledgerfemic.hydrology.disturbance.v1validation_reportfemic.hydrology.validation.v1model_cardfemic.hydrology.model_card.v1pilot_runfemic.hydrology.pilot.v1
surrogate_validation, frequency_pairing, and benchmark_check are
opaque JSON artifacts at this layer and must record their own caveats.
Manifest Contract
The manifest records:
bundle_idandbundle_name;bundle_versionandgenerated_utc;domain_id,ledger_id, andresponse_surface_id;artifact records with relative path, role, schema, media type, size, and SHA-256;
response-surface summary and flood-risk summary;
applicability_domainanduncertainty;consumer_contract;caveats and provenance.
bundle_id is hydro-response- followed by a deterministic digest of the
canonical plan and materialized artifact records. Identical inputs produce the
same bundle_id; bundle_name appends the bundle version.
Artifact and Path Rules
Artifact paths must remain inside the bundle.
The manifest must not reference absolute paths.
The builder copies bytes without rewriting artifact JSON.
Domain and ledger artifact IDs must match the plan; the flood-risk table must name the planned response surface.
Artifact checksums are lowercase SHA-256 over exact file bytes.
The builder refuses to overwrite a non-bundle directory.
--overwritereplaces only a directory containing a valid FEMIC response manifest.
Flood-Risk Table Contract
A flood-risk table records:
table_id,generated_utc,source_surface_id, andbaseline_name;one row per
receptor_idandreturn_period;watershed_id;baseline and scenario peak flow in cubic metres per second;
ratioequal to scenario/baseline flow;optional exceedance probability in
[0, 1];optional expected annual damage, non-negative;
caveats.
The table is a screening product. It does not define a regulatory flood construction level, floodway, or design flood.
Applicability And Uncertainty
The manifest records the applicability domain supplied by the plan or extracted from a packaged surrogate model. Consumers must refuse queries outside that domain unless a reviewed extrapolation is explicitly approved.
Uncertainty recorded in the plan is merged with available held-out surrogate
metrics (rmse, mae, r2, coverage_95). It is descriptive
metadata, not a calibrated predictive distribution.
Consumer Handshake
WS4 P49 and FHOPS P14 must:
Resolve the pinned
bundle_idandbundle_version.Read and validate
manifest.json.Verify all artifact sizes and SHA-256 values.
Read the response surface, then the flood-risk table.
Read the applicability domain and refuse unsupported queries.
Preserve CRS, units, return periods, caveats, and producer provenance.
Avoid re-running FEMIC discovery, frequency fitting, or surrogate training.
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