This proposed integration contract connects Storm Forecast, Alert, Radar, Map, Impact, Report, History, and Replay. The first release implements the subset needed for a reviewed Missouri briefing, not every future capability. The implementation evidence below comes from the checkout, not a live production audit. Capability names do not create new services or change deployment ownership.
Paths are relative to the repository root.
| Capability | Existing implementation | Remaining integration |
|---|---|---|
| Storm Forecast | No SPC outlook ingestion or forecast capability is linked. | Approved product/interface contract, issuance history, preparation view, and freshness policy. |
| Storm Alert | org/apps/hail-alerts/worker/nws.ts, evaluation.ts, and coordinator.ts: bounded NWS retrieval, observed-hail qualification, warning-chain decisions, and controlled delivery. |
Unified user entry, authenticated return, and warning-to-storm/evidence association. Broader warning eligibility needs an explicit policy change. |
| Storm Radar | org/apps/data/worker/discovery.ts, products.ts, and ingestion.ts: MRMS S3 polling, MESH and lowest-altitude reflectivity, provenance, and derived artifacts. |
Warning-context evidence association, quality policies, and additional native product contracts where required. |
| Storm Map | org/apps/data/worker/revisions.ts, mrms-history.ts, and event-room.ts; org/apps/ui/src/mrms/watchStormRevisions.ts; shared map code under org/apps/ui/src/lib/map/. |
Physical-storm detection and tracking, split/merge lineage, per-storm selection, and the complete alert-to-map handoff. |
| Storm Impact | Data catalog schemas and the Missouri research corpus. | Accepted county/work-area geometry and weather-area ranking for the report; later parcel releases, residential/roof identity, outcome labels, and calibration. |
| Storm Report | No implemented generator, dashboard report record, or report-delivery workflow is linked. | Retained evidence, review/publication, authorized email link, mobile report, acknowledgment, and recovery. |
| Storm History | org/apps/data/worker/mrms-history.ts, revisions.ts, and backfill.ts: bounded event/revision reads and benchmark windows. |
Customer discovery, complete-range retrieval, durable saved evidence, report links, retention availability, and access. |
| Storm Replay | org/apps/ui/src/components/StMapHistoryBar.vue, org/apps/ui/src/machines/timelineMachine.ts, and MRMS map integration. |
Observation/correction policy, knowledge cutoffs, deep links, retained report playback, and product acceptance. |
The active mrms-conus ID is a national feed container. A revision API with
storm-events in its path does not prove that physical storms are detected.
The separate warning application is not already connected to the command center.
Application references own runtime boundaries. The live revision reference owns implemented revision publication and retention details.
These are proposed fields and relationships, not implemented endpoint schemas.
| Handoff | Context retained | When a dependency is missing |
|---|---|---|
| Forecast → Alert | Outlook product/issuance, valid period, hazard semantics, preparation scope, and warning association only when supported. | Alerts remain independent; an outlook is not a warning prerequisite or a neighborhood impact claim. |
| Alert → Radar | Warning ID/chain/revision, issuer, valid interval, geometry, triggering policy, and notification identity. | Open warning context with evidence pending; do not infer radar confirmation. |
| Radar → Map | Evidence IDs and source versions, observation times, spatial association, physical-storm ID when established, event revision, and quality caveats. | Show the source extent and unresolved association; do not mislabel the national feed as a physical storm. |
| Map → Impact | Analysis-scope ID (physical-storm ID/revision when established), selected time, geography, filters, exposure window, and data/model versions. | Preserve the map and identify unavailable ranking inputs. |
| Impact → Report | Ranking snapshot/mode, county and work-area geometry, source cutoff, coverage, reviewer, and report ID/revision. | Keep a draft or partial county briefing; no invented neighborhood or complete assignment. |
| Report → Recipient | Published revision, tenant/audience, delivery identity, access, current safety status, and explicit acknowledgment. | Retry failed delivery without republishing; hold field assignment when safety information is missing or conditions are dangerous. |
| History → Replay | Scope kind/ID, requested/available window, pinned revisions, geometry, coverage, access, and playback mode. | Disclose partial, expired, or restricted history without substituting live evidence. |
| Report → History/Replay | Exact published report and evidence revisions, ranking snapshot, and supersession information. | Preserve the report and identify missing evidence; a saved link alone cannot guarantee replay. |
| Impact → Parcel | Ranking snapshot, selected geographic path, stable parcel ID and source release, roof links where known, reasons, and next permitted action. | Preserve unknown roof attributes and distinguish unranked from low priority. |
History and Replay support all stages; they are not additional chronological steps after Report. Their shared contract owns time modes, retention, and deterministic test acceptance.
A useful task context identifies the selected snapshot rather than depending on an agent or browser to remember it:
kind: storm-journey-context
status: proposed-template
forecast_issuance: null
analysis_scope_id: null
report_id: null
report_revision: null
warning_id: null
warning_revision: null
storm_id: null
storm_revision: null
selected_observation_time: null
view_mode: history # live or history
replay_mode: evidence-timeline # as-known-then requires availability history
knowledge_cutoff: null
history_window: null
selected_revision_ids: []
geographic_path: []
source_versions: []
parcel_release: null
ranking_snapshot: null
ranking_mode: null
model_or_rule_version: nullNull means unresolved, not an invented identifier or approved empty result. Authorization and user identity are separate access concerns; this manifest must not contain session credentials or grant access.
| Surface | Required states or distinctions |
|---|---|
| Forecast | Issued/valid period, current or superseded issuance, stale/unknown availability; missing contours are not an all-clear. |
| Warning | Active, updated, cancelled, expired; preserve publisher history. |
| Evidence | Pending, available, partial, stale, unavailable; preserve source time and limits. |
| Map | Live edge, historical selection, buffered updates, reconnecting, unavailable frame. |
| Impact | Computing, ready, partial coverage, stale snapshot, unranked, failed validation. |
| Report | Draft, validated, reviewed, published, superseded, withdrawn; preserve published revisions. |
| History | Loading, available, partial, uncollected, expired, restricted, failed; incomplete search is not no storm. |
| Replay | Paused, playing, seeking, buffering, ended, missing frame; time mode and correction policy stay visible. |
| Delivery | Queued, provider-accepted, delivered or failed when evidenced; viewing and acknowledgment are separate. |
Operational values need timestamped observations. A configured two-minute poll is a schedule, not a freshness guarantee. Numeric lag tolerances and source quality thresholds remain open decisions until approved.
| Check | Required result |
|---|---|
| Prepare without a warning | Forecast retains hazard/validity semantics and does not invent an alert or damage prediction. |
| Publish a pilot report | Meet the report release acceptance, including real delivery, mobile use, access, and recovery. |
| Open a warning before MRMS is ready | Warning remains usable; evidence is explicitly pending. |
| Open an expired notification | Original warning revision is retained; current status is visible. |
| Reconcile a cancelled or updated warning | Pending delivery follows the app's policy; historical evidence is not erased. |
| Associate overlapping warnings and radar | Association retains method, time, geometry, and uncertainty; identities stay distinct. |
| Reopen retained pilot evidence | Meet the History and Replay acceptance in the customer view and isolated tests. |
| Receive a revision while viewing history | Selected frame, viewport, filters, and rank snapshot remain stable; updates are buffered. |
| Reconnect after missed notices | Reconcile from authoritative history; duplicates do not replay actions. |
| Track a splitting or merging storm | Parent/child lineage and warning associations remain explainable. |
| Drill down through a county-crossing ZCTA | Only the selected county portion is included; aggregate units are not double-counted. |
| Compare incomplete counties | Coverage is visible; missing data never produces a zero-impact claim. |
| Return to an earlier impact result | Original evidence, data releases, membership rules, and scoring revision reproduce the result. |
These are implementation acceptance criteria. Passing documentation checks does not demonstrate that the runtime journey satisfies them.
- Select a Missouri pilot scope and approve county/work-area geometry, MRMS evidence rules, and a warning or operator-selected analysis window.
- Produce reproducible weather-exposure priorities and reviewed starting areas, retaining the inputs needed for report replay. Build the bounded History entry and Replay view against shared manifests, with tests for time order, missing frames, corrections, and isolated execution.
- Implement report review, immutable publication, dashboard discovery, authorized email delivery, and a mobile recipient view with acknowledgment.
- Prove the report acceptance contract with a real pilot, including reopening its evidence from History and Replay. Missing parcels and Forecast ingestion do not block this slice.
- Add Forecast preparation, full physical-storm tracking, broader geographic rollout, parcel exposure, and eventually validated replacement modeling as separately bounded increments.
Each task should pin source/code revisions, expected states, local verification, publication authority, recovery behavior, and remaining gaps. Use the shared product review and operations guides for the actual owning applications; capability names do not require duplicated scripts or services.
Open decisions include pilot geography and recipients, approved boundaries and work areas, warning eligibility, evidence freshness and quality, exposure thresholds, retention, and delivery policy. Later work also needs physical-storm association and residential/roof outcome definitions. Documentation readiness is not runtime proof or an installed notification schedule.