# Storm events and revisions

Product design

This page describes the product model and requirements. Examples illustrate the model, not a guaranteed API or completed feature. Check the [application contracts](/stormtrust/apps/) and [dataset inventory](/stormtrust/product/platform-and-data/datasets-and-source-contracts/) for implemented scope. Use [operations guides](/stormtrust/engineering/operations/) for runnable procedures.

A physical storm is distinct from a publisher warning, an MRMS frame, a derived revision, a forecast issuance, a report, and a notification. Preserving these identities makes the eight-capability system auditable.

## Identity boundaries

| Entity            | Identity and role                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| Forecast issuance | Publisher outlook product and issuance with its hazard definition and valid period.                                   |
| Analysis scope    | Selected geography and evidence window, with warning references where relevant; can contain multiple physical storms. |
| Report revision   | Immutable reviewed briefing referencing an analysis scope, ranking snapshot, and authorized audience.                 |
| Warning           | Publisher message and warning-chain identity, with issuance/update/cancellation history.                              |
| MRMS observation  | Source product, object version, observation time, and native spatial extent.                                          |
| Physical storm    | Stable tracked event with evidence-backed association and split/merge lineage.                                        |
| Revision          | Immutable interpretation of evidence for a named event or feed container.                                             |
| Notification      | Recipient/policy/delivery decision referencing the triggering warning or revision.                                    |
| Ranking snapshot  | Versioned geographic priorities tied to the event revision and data/model versions.                                   |

The existing `mrms-conus` ID identifies the operational national feed. Do not present it as a detected physical storm. A benchmark ID names a selected time window. The physical-storm association model remains a product requirement. The first [Storm Report](/stormtrust/product/platform-and-data/intelligence/storm-report/) can use an explicit regional analysis scope before that tracker exists; a selected window is not proof of a single physical storm.

Source association can be many-to-many. Preserve the method, version, temporal window, spatial overlap, confidence, and unresolved cases. A storm split or merge needs explicit parent/child lineage rather than an unexplained identity change. A cancelled warning does not, by itself, prove the physical storm ended.

[Storm History](/stormtrust/product/platform-and-data/intelligence/storm-history/) indexes retained identities; [Storm Replay](/stormtrust/product/platform-and-data/intelligence/storm-replay/) selects observations and revisions without creating a new physical storm for each playback frame. Observation time and publication order remain separate.

## Event detection

Event detection considers temporal and spatial continuity, hail thresholds, storm motion, source agreement, radar gaps, cell splitting, and cell merging.

## Stable event identity

An event ID survives ordinary revisions. A changed boundary does not produce an unrelated event solely because its geometry changed.

## Event status

Suggested event states are:

```txt
anticipated
active
reconciling
ended
reviewed
archived
```

An event can end before it is fully reconciled.

## Event boundaries

Each boundary retains geometry, derivation method, threshold, event revision, source products, confidence, time range, and simplification details.

## Severity

Severity is multi-dimensional. Potential components include maximum estimated hail, severe-hail probability, affected area, affected structures, confidence, duration, and commercial exposure.

The public interface may display a simpler severity level. The underlying components remain available.

## Confidence

Confidence explanations state why StormTrust supports a conclusion.

A high-confidence explanation could cite a strong MESH signal, strong POSH, good radar coverage, a persistent track, and spatially consistent ground reports.

A moderate-confidence explanation could cite a strong aloft estimate with limited near-surface corroboration.

## Evidence timeline

The proposed event ledger distinguishes source and processing times. This fictional timeline illustrates the relationship:

```txt
18:02  SPC outlook includes region
19:03  NWS severe thunderstorm warning
19:08  MESH crosses 1.00 in
19:10  POSH crosses configured threshold
19:12  Storm event created
19:14  Boundary expands
19:19  Ground hail report received
19:22  Property impacts recalculated
20:11  Event marked ended
21:04  Late report reconciled
```

## Storm tracks

Tracks support time animation, swath accumulation, directional movement, timeline synchronization, and historical playback.

## Cumulative exposure

A property may experience repeated hail exposure:

```txt
Property
   ├── Event A: 1.10 in
   ├── Event B: 1.35 in
   ├── Event C: 1.70 in
   └── cumulative exposure profile
```

Cumulative exposure is a history model. StormTrust does not add hail sizes together as if they were an arithmetic accumulation.

## Human review

Authorized reviewers may confirm, reject, annotate, adjust, certify, or request reprocessing. Audit history records every human action. Review does not destroy the automated result.