Document internal component boundaries

docs/internal/forecast-derivation.md

@@ -1,57 +1,66 @@
 # Forecast Derivation Internals
 
-This document describes the implemented deterministic forecast summarization
-boundary.
+This document describes deterministic forecast summarization in
+`internal/forecast`.
 
 ## 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.
+`internal/forecast` converts normalized bundle data into daily and period
+summaries used by briefing builders.
 
-## Inputs and Outputs
+## 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
+- local date or resolved report period
+- timezone
+- configured daypart definitions
 
-Output:
+Outputs:
 
-- `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.
+- `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 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`.
+- 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.
 
-## Behavior
+## Config Fields Used
 
-- 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.
+- `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 `forecast.Bundle`.
+
+## State Or Manifest Behavior
+
+None. Source warnings and provenance from the bundle are carried into summaries
+for later metadata and briefing output.
+
+## Skip And Resume Behavior
+
+None. Missing optional source context can produce empty selections, but missing
+required hourly data fails summarization.
 
 ## 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.
+- 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
 
@@ -62,7 +71,6 @@ Inspect:
 
 ## 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.
+- 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.