This proposed product contract supports Storm History and Storm Replay. They share evidence and read contracts with live views and testing. This page defines required behavior; it does not create a historical archive, new API, backfill permission, retention schedule, or replay runner.
| Capability | Owns |
|---|---|
| History | Discovery by supported place/time filters, record identity, coverage, retention availability, and reopening a selected revision. |
| Replay | Playback and seek state, time interpretation, correction selection, gaps, live-update buffering, and comparison context. |
| Map | Geographic presentation, layers, viewport, legends, and synchronized selection. |
| Radar | Native weather evidence, source units, provenance, and scientific limits. |
| Impact and Report | Versioned ranking results and reviewed publication; replay cannot mutate either. |
Capability names do not prescribe separate Worker applications. Reuse the actual application graph, decoder, revision manifests, and read paths. Keep test execution, public weather reads, and tenant-private product actions under their appropriate authority.
Paths are relative to the repository root. These are checkout observations, not an audit of deployed data availability.
| Evidence | Existing behavior | Gap for the product |
|---|---|---|
org/apps/data/worker/mrms-history.ts |
Event and revision reads return bounded lists; the runtime reference owns their limits. | Search, pagination, complete-range retrieval, and coverage guarantees are not supplied by these bounded lists. |
org/apps/data/worker/revisions.ts |
Reads ready revisions by publication sequence and retains revision/product identity. | An observation-time playback policy and historical knowledge-cutoff selection must handle corrections explicitly. |
org/apps/data/worker/backfill.ts and benchmarks/ |
Checked-in benchmark windows use the shared ingestion and revision machinery. | General customer archive retention and permissioned backfill requests need their own contract. |
org/apps/ui/src/components/StMapHistoryBar.vue and src/machines/timelineMachine.ts |
Play/pause, seek, and frame-index playback controls exist; the timeline machine advances at a configured interval and loops. | Product speed/gap/end-of-window behavior, deep links, and full historical comparison need acceptance evidence. |
org/apps/ui/src/mrms/watchStormRevisions.ts and src/map/liveMrmsMapViewController.ts |
Revision notices and map history integration provide a foundation for live/replay transitions. | Verify durable selection, reconnect, report context, and correction behavior through the complete user journey. |
The paths abbreviated with src/ in the UI rows are relative to org/apps/ui/;
benchmarks/ is under org/apps/data/. The active mrms-conus feed and named
benchmark windows are not automatically tracked physical storms. An API response
with mode: live identifies the current source mode, not proof its observations
are fresh or that the viewer is following the live edge.
The implemented revision reference owns current publication and retention details. The local benchmark procedure owns runnable commands. Do not invent a production mutation endpoint from an internal benchmark route.
| Group | Required context |
|---|---|
| Identity | Feed/analysis-scope/physical-storm kind and ID, selected revision IDs, and report ID/revision when entered from a report. |
| Geography | Selected extent and county/work-area IDs, boundary versions, layers, and filters. |
| Observation | Requested start/end, included observations, missing intervals, source products and versions, units, and quality. |
| Availability | Source issue/observation time, local receipt time, ready/publication time, retrieval cutoff, and any revision supersession. |
| Playback | Evidence-timeline or as-known-then mode, cursor time, play/pause state, speed, correction policy, and buffered live revisions. |
| Reproduction | Analysis/rule version, input manifest and hashes, retained artifact references, coverage, and validity limits. |
| Access | Audience and authorization decision; a saved URL contains no credentials and grants no access by itself. |
Default to a bounded observation-time timeline with a pinned revision selection. Publication sequence is useful for detecting updates; it is not observation chronology. When several revisions describe the same observation, retain all identities and show which version the selected view uses. Establish the revision-selection rule before enabling playback of corrected frames.
For as known then, exclude evidence received or made available after the knowledge cutoff, even when its observation time is earlier. A source backfill performed today can support retrospective analysis but does not prove what the application knew yesterday. Missing availability history makes reconstruction unknown. Forecast issuance, warnings, radar frames, ranking snapshots, and reports must each honor their applicable cutoff.
New data or rules produce a separate retrospective result with an explicit comparison basis. Reproduce the old result from its pinned inputs before attributing a difference to an algorithm change. Replay alone does not rerun an ingestion pipeline or produce a new Impact assessment.
History must distinguish an empty result from an incomplete query, uncollected window, partial ingest, expired artifact, restricted record, or read failure. Expose requested versus available intervals, product coverage, and truncation. A response that fills its frame limit is not proof of a complete storm.
Approve a retention policy for each saved product artifact: raw inputs, derived frames, manifests, warnings/outlooks, geography, ranking snapshots, reports, and permitted field observations. Record its owner, expiration, retention or deletion basis, and what remains reproducible after cleanup. A catalog record or immutable ID alone does not preserve referenced bytes.
Before promising report replay, retain and verify the required evidence and versions for that promised period. Protect referenced inputs from conflicting cleanup, and test reads after the ordinary operational retention boundary. Benchmark exclusion from current cleanup is not a customer retention promise or a backup/restore guarantee. Recovery needs artifact integrity and read evidence.
A missing historical window may lead to a separately authorized backfill when source access, availability, scope, cost, and quotas permit. Reading History or pressing Play must not trigger an unbounded extraction. Keep backfill status separate from playback; accepted work is not completed history.
Use the same production-shaped input manifests, schema validation, decoder, revision reads, and presentation behavior for retained real evidence and explicitly labeled fixtures. Keep expected results and run records separate from customer history. A fixture must not appear as a measured storm or report.
A deterministic test packet pins its window, source bytes/hashes, arrival and availability schedule, geography, rule/code versions, execution clock, expected states, and known limitations. Use isolated state and controlled delivery adapters. Playback and regression runs must not send real alerts or reports, change production rankings, or advance live processing checkpoints.
Test reproduction against frozen inputs and the original rule. Test a new algorithm as a separately labeled retrospective evaluation. Record changed inputs as well as changed code; do not silently refresh the benchmark from the network. The evaluation reference owns outcome labels and leakage controls. Radar replay is not roof-damage ground truth.
| Scenario | Product and test evidence |
|---|---|
| Find and reopen a pilot window | Place/time or pilot-list selection returns the correct scope, coverage, and revision; back navigation preserves the query. |
| Enter from a sent report | Replay opens the exact published evidence and ranking snapshot, with any supersession visible. |
| Advance through a missing frame | The timeline shows the gap, its duration and reason where known; it does not fabricate an observed track. |
| Receive late evidence or a correction | Observation order and publication order remain distinct; as-known-then excludes evidence after its cutoff. |
| Receive live updates while paused | Position, viewport, layers, and geographic path remain pinned; an explicit action returns to latest. |
| Reconnect or retry | Reconcile revision identities, preserve selection, and avoid duplicate frames or operational side effects. |
| Reach the end of the selected window | Stop by default; any loop is explicitly selected and labeled. Returning to the first frame cannot imply continuous storm movement. |
| Replay after operational cleanup | Promised retained inputs still resolve; expired or unavailable inputs are disclosed without substituting newer evidence. |
| Open restricted history | Tenant-private reports and evidence remain protected across search, deep links, manifests, and downloads. |
| Run a deterministic benchmark | Identical pinned inputs and clock yield expected states; no live notification or production mutation occurs. |
| Use a phone or keyboard | Play/pause, step, seek, timestamps, and an equivalent event list are usable without relying on animation. |
Support the first report with a retained pilot-window entry, an immutable report evidence link, and playback of its available observations. Prove gaps, late revisions, access, and recovery using the same contracts in local benchmarks and customer views. Preserve availability timestamps now so later as-known-then work is possible; do not claim that mode works before it is tested.
Expand into broader geographic search, authorized backfills, full physical-storm history, and comparison tools after the bounded slice is reliable. These capabilities are product foundations, while the Storm Report pilot remains the first end-to-end release target.