weatherreporter/docs/internal/facts.md

Fact Contracts Internals

This document describes the fact contract boundary.

Purpose

internal/facts separates normalized upstream facts collected for a report run from conservative report-scoped facts derived from them. The package gives app orchestration one place to build reusable facts before module execution.

Inputs And Outputs

Inputs:

• weatherdata.Bundle from the Weather API adapter
• resolved report definition and valid period
• report timezone
• configured daypart definitions

Outputs:

• facts.CollectedFacts with normalized source facts plus separate source provenance and warnings. SPC convective outlook source data is carried through when present in the bundle, including upstream geometry and source provenance.
• facts.DerivedFacts with valid-period forecast slices, alert overlaps, report-period SPC convective outlooks and discussions, daily summaries, daypart summaries, and Storm Report window summary

Near-Term Report uses the generic valid-period hourly and narrative selection for its rolling six-hour window. Its derived facts include precipitation timing from the selected hourly periods, alert overlaps for the six-hour period, and SPC outlooks/discussions overlapping that period. It does not build daily summaries, daypart summaries, or a storm-window summary.

Boundaries

• This package owns fact assembly and reusable deterministic derivation for a report run.
• SPC convective outlook derivation selects already-collected outlooks whose half-open valid intervals overlap the resolved report period and retains discussions for represented outlook days.
• Derived SPC outlook records preserve the collected outlook fields, including geometry, for downstream components that need source-level facts. Prompt modules decide which fields are exposed to Scriptorium.
• It does not fetch upstream data, build prompt wording, compare prior snapshots, write workflow state, invoke Scriptorium, or define modules.

Config Fields Used

• dayparts[].name
• dayparts[].start
• dayparts[].end
• weather_api.timezone

External Adapters Used

None directly. Collected facts are built from weatherdata.Bundle.

State Or Manifest Behavior

None. Source provenance and warnings remain data fields for downstream metadata and inspection.

Failure Behavior

• Invalid or missing report valid periods return an error.
• Invalid timezone names return an error.
• Missing required hourly forecast data returns the underlying forecast derivation error for reports that require daily summaries.
• Near-Term Report can derive its default module facts without daily or daypart summaries.
• Missing optional narrative, alert, discussion, daily, or weather story data produces empty or nil derived fields.
• Missing optional SPC convective outlook data produces a nil collected field.
• A present SPC convective outlook source with no report-period matches produces non-nil empty derived outlook and discussion slices.

Tests

Inspect:

• internal/facts/facts_test.go
• internal/app/app_test.go

Invariants

• Collected facts are built once from a fetched bundle.
• Derived facts are scoped to one resolved report.
• SPC convective outlook selection uses the resolved report period and the already-collected outlook run.
• Source provenance and warnings stay separate from ordinary fact fields.
• Prompt-specific wording and one-off presentation decisions stay outside this package.