# 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.