weatherreporter/docs/internal/forecast-derivation.md

# Forecast Derivation Internals

This document describes deterministic forecast summarization in
`internal/forecast`.

## Purpose

`internal/forecast` converts normalized weather data into daily and period
summaries used by fact builders and module builders.

## Inputs And Outputs

Inputs:

- `weatherdata.Bundle`
- local date or resolved report period
- timezone
- configured daypart definitions

Outputs:

- `forecast.DailySummary` for one local civil day
- one clipped daily summary per local day or partial day from
  `BuildPeriodDailySummaries`
- daypart summaries with selected hourly periods, ranges, timed maximums,
  conditions, indicators, and alert overlaps

## Boundaries

- This package groups, selects, and summarizes already-normalized forecast
  data.
- It does not perform HTTP calls, parse CLI flags, resolve report definitions,
  compare prior snapshots, build prompt input packages, or invoke Scriptorium.

## Config Fields Used

- `dayparts[].name`
- `dayparts[].start`
- `dayparts[].end`

Threshold constants for basic indicators live in forecast code rather than
configuration.

## External Adapters Used

None directly. Forecast data arrives through `weatherdata.Bundle`.

## State Or Manifest Behavior

None. Source warnings and provenance from the bundle are carried into summaries
for later metadata and module output.

## Skip And Resume Behavior

None. Missing optional source context can produce empty selections, but missing
required hourly data fails summarization.

## Failure Behavior

- A nil bundle or missing hourly forecast data returns an error.
- Invalid daypart definitions return parse errors with context.
- Alert records without parseable RFC3339 timing are skipped.
- Empty selected periods produce empty summaries rather than generated prose.

## Tests

Inspect:

- `internal/forecast/derive_test.go`
- `internal/timeutil/periods_test.go`

## Invariants

- Go owns report-period selection and meteorological summarization.
- Weather facts come from normalized source data.
- Outputs remain JSON-inspectable and independent of CLI, state, and adapters.