69 lines
2.3 KiB
Markdown
69 lines
2.3 KiB
Markdown
# Forecast Derivation Internals
|
|
|
|
This document describes the implemented deterministic forecast summarization
|
|
boundary.
|
|
|
|
## Purpose
|
|
|
|
`internal/forecast` converts a normalized forecast bundle into inspectable
|
|
daily and multi-day daypart summaries. These summaries are structured data for
|
|
later briefing builders; they are not rendered report text.
|
|
|
|
## Inputs and Outputs
|
|
|
|
Inputs:
|
|
|
|
- `forecast.Bundle`
|
|
- local date and timezone
|
|
- report period, for multi-day summaries
|
|
- configured daypart definitions with `HH:MM` start and end values
|
|
|
|
Output:
|
|
|
|
- `forecast.DailySummary` with a civil-day period, daypart summaries, selected
|
|
narrative periods, alert overlaps, discussion context, source warnings, and
|
|
source provenance.
|
|
- `forecast.BuildPeriodDailySummaries` output with one clipped daily summary
|
|
for each local day or partial day in a report period.
|
|
|
|
## Boundaries
|
|
|
|
- This package groups and summarizes already-normalized forecast data.
|
|
- It does not fetch weather data, resolve report definitions, compare prior
|
|
snapshots, build prompt input packages, or call `scriptorium`.
|
|
|
|
## Behavior
|
|
|
|
- Daypart windows use half-open intervals.
|
|
- Overnight dayparts are supported when the end clock is not after the start
|
|
clock.
|
|
- Hourly forecast periods are selected by overlap with the daypart window.
|
|
- Each daypart computes temperature range, apparent-temperature range, maximum
|
|
precipitation probability, peak wind speed, peak wind gust, dominant
|
|
condition, notable conditions, and basic weather indicators.
|
|
- Alerts are selected by overlap with the daily period and each daypart.
|
|
- Narrative periods and discussion context are selected as broader source
|
|
context for later briefing builders.
|
|
- Multi-day period summaries clip the first and last local days to the resolved
|
|
report period before selecting hourly periods and alerts.
|
|
|
|
## Failure Behavior
|
|
|
|
- Missing hourly forecast data returns an error.
|
|
- Invalid daypart definitions return actionable parse errors.
|
|
- Alert records without parseable RFC3339 start/end fields are skipped.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/forecast/derive_test.go`
|
|
- `internal/timeutil/periods_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Weather facts come from normalized source data, not generated prose.
|
|
- Outputs remain JSON-inspectable.
|
|
- Forecast derivation remains independent of CLI, HTTP adapters, and report
|
|
registry behavior.
|