Add collected and derived fact contracts

docs/internal/app-orchestration.md

@@ -6,10 +6,10 @@ This document describes the implemented workflow coordinator in `internal/app`.
 
 `internal/app` coordinates the top-level use cases after CLI parsing and config
 loading are complete. It resolves report definitions, fetches weather data,
-builds briefing and prompt-input artifacts, invokes Scriptorium through the
-adapter boundary, optionally notifies distributor through an app-owned notifier
-boundary, persists managed state, runs batches, and reads existing artifacts for
-inspection.
+builds collected and derived facts, builds briefing and prompt-input artifacts,
+invokes Scriptorium through the adapter boundary, optionally notifies
+distributor through an app-owned notifier boundary, persists managed state, runs
+batches, and reads existing artifacts for inspection.
 
 ## Inputs And Outputs
 
@@ -21,7 +21,7 @@ Inputs:
 - `BriefingRequest` and `ReportRequest` for package-level orchestration tests
   and internal composition
 - resolved report definitions from `internal/report`
-- forecast bundles from `internal/adapters/weatherapi`
+- weather data bundles from `internal/adapters/weatherapi`
 - prior snapshots loaded from `internal/state`
 - optional renderer, notifier, and state-store fakes for tests
 
@@ -39,11 +39,12 @@ Outputs:
 ## Boundaries
 
 `internal/app` owns workflow order and request composition. It does not parse
-CLI flags, load YAML files directly, implement HTTP transport, derive forecast
-facts, define report periods, compare rendered Markdown, or construct
-Scriptorium argv.
+CLI flags, load YAML files directly, implement HTTP transport, own fact
+derivation algorithms, define report periods, compare rendered Markdown, or
+construct Scriptorium argv.
 
 Report selection and report identity policy come from `internal/report`.
+Collected and derived fact contracts come from `internal/facts`.
 Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
 subprocess behavior stays in `internal/adapters/scriptorium`. Distributor
 upload behavior stays in `internal/adapters/distributor`. Filesystem layout and

docs/internal/briefing.md

@@ -5,9 +5,8 @@ This document describes the implemented briefing package boundary.
 ## Purpose
 
 `internal/briefing` builds structured report-specific briefing packages from
-resolved report metadata, forecast bundles, and derived forecast summaries.
-Briefings are curated inputs for prompt data packages, not rendered report
-prose.
+resolved report metadata, collected weather data, and derived forecast facts.
+Briefings are curated inputs for prompt data packages, not rendered report prose.
 
 ## Inputs And Outputs
 
@@ -15,7 +14,7 @@ Inputs:
 
 - resolved report definition, generation time, timezone, and valid period
 - `weatherdata.Bundle` with source provenance and warnings
-- derived daily or period summaries where required
+- derived daily, period, or storm-window facts where required
 - configured units, timezone, and descriptive location context
 
 Outputs:
@@ -37,7 +36,7 @@ Outputs:
 ## Config Fields Used
 
 The package receives configured units and timezone from the app layer. Daypart
-configuration is consumed by `internal/forecast` before briefing builders run.
+configuration is consumed by `internal/facts` before briefing builders run.
 Configured `location` values are prompt context only; Weather API
 `sourceLocationId` and `sourceLocation` remain source provenance.
 Current conditions are copied from the normalized `/conditions/current` bundle

docs/internal/facts.md

@@ -0,0 +1,72 @@
+# Fact Contracts Internals
+
+This document describes the implemented 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 briefing construction.
+
+## 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
+- `facts.DerivedFacts` with valid-period forecast slices, alert overlaps,
+  daily summaries, daypart summaries, and Storm Report window summary
+
+## Boundaries
+
+- This package owns fact assembly and reusable deterministic derivation for a
+  report run.
+- 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.
+- Missing optional narrative, alert, discussion, daily, or weather story data
+  produces empty or nil derived fields.
+
+## 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.
+- Source provenance and warnings stay separate from ordinary fact fields.
+- Prompt-specific wording and one-off presentation decisions stay outside this
+  package.

docs/internal/forecast-derivation.md

@@ -5,8 +5,8 @@ This document describes deterministic forecast summarization in
 
 ## Purpose
 
-`internal/forecast` converts normalized `weatherdata` bundle data into daily
-and period summaries used by briefing builders.
+`internal/forecast` converts normalized weather data into daily and period
+summaries used by fact builders and briefing builders.
 
 ## Inputs And Outputs
 

docs/policy/development.md

@@ -19,6 +19,7 @@ Developers and LLM coding agents should use it with
 - `internal/weatherdata`: normalized weather source facts, source metadata, and
   source warnings.
 - `internal/forecast`: deterministic forecast derivation.
+- `internal/facts`: collected and derived report fact contracts.
 - `internal/report`: report definitions, valid periods, batches, output names,
   and comparison declarations.
 - `internal/briefing`: report-specific briefing package builders.