Refresh deterministic domain documentation

docs/internal/forecast-derivation.md

@@ -1,76 +1,63 @@
 # Forecast Derivation Internals
 
-This document describes deterministic forecast summarization in
-`internal/forecast`.
+`internal/forecast` deterministically selects and summarizes normalized
+forecast data. It has no transport, filesystem, CLI, subprocess, or report
+registry dependency. Its summaries are consumed by
+[fact contracts](facts.md) and later module builders.
 
-## Purpose
+## Period and daypart semantics
 
-`internal/forecast` converts normalized weather data into daily and period
-summaries used by fact builders and module builders.
+Selections use `timeutil.Period` half-open overlap: a value is selected only
+when both intervals share time. `BuildDailySummary` creates one local civil
+day; `BuildPeriodDailySummaries` intersects every local civil day with the
+requested period, preserving partial first and last days.
 
-## Inputs And Outputs
+`ResolveDayparts` converts each configured name, start clock, and end clock
+into a local window. An end clock at or before its start clock wraps into the
+next civil day. The daypart and timezone defaults are defined in the
+[configuration reference](../config.md), not here.
 
-Inputs:
+## Deterministic summaries
 
-- `weatherdata.Bundle`
-- local date or resolved report period
-- timezone
-- configured daypart definitions
+`BuildDailySummary` requires an hourly run with at least one period. It adds
+the selected narrative periods, discussion, alert overlaps, source provenance,
+source warnings, and one `DaypartSummary` per resolved window. A daypart keeps
+its selected hourly periods and derives temperature and apparent-temperature
+ranges, timed precipitation and wind maxima, dominant and notable conditions,
+and weather indicators.
 
-Outputs:
+Indicators are deterministic checks over normalized values and condition text:
+heat, cold, and wind use package-owned numeric cutoffs; snow, ice, fog, and
+wind text are detected from the forecast description. `BuildPrecipTiming`
+sorts periods, records the maximum and first precipitation, groups contiguous
+periods at or above its package-owned probability threshold, and records
+thunder mentions.
 
-- `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
+Alert overlap parsing supports the normalized alert payload's available timing
+fields. Unparseable alerts and invalid intervals are ignored; valid overlaps
+are clipped to the requested period and ordered by alert start time.
 
-## Boundaries
+## Missing data and failures
 
-- 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.
+Empty selections yield empty summary fields rather than generated prose.
+Direct daily or period-summary calls fail when their required bundle, valid
+period, hourly data, or daypart definitions are invalid. A nil location uses
+UTC when these APIs are called directly. Optional narrative, discussion, and
+alerts remain absent when their normalized products are absent.
 
-## Config Fields Used
+Forecast thresholds used for brief indicators and precipitation timing are
+implementation rules. User-configurable Recent Changes thresholds are applied
+by [changes internals](changes.md), whose defaults are documented in
+[configuration](../config.md).
 
-- `dayparts[].name`
-- `dayparts[].start`
-- `dayparts[].end`
+## Verification and invariants
 
-Threshold constants for basic indicators live in forecast code rather than
-configuration.
+Focused tests cover local civil days, clipped periods, daypart resolution,
+summary metrics, precipitation windows, threshold helpers, and alert overlap:
 
-## External Adapters Used
+```sh
+go test ./internal/forecast ./internal/timeutil
+```
 
-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.
+The package preserves normalized inputs as inspectable structured values and
+never decides report identity, delivery, or presentation wording.