Document internal component boundaries

docs/internal/weather-data.md

@@ -1,59 +1,74 @@
 # Weather Data Internals
 
-This document describes the implemented weather data ingestion boundary.
+This document describes Weather API ingestion into `forecast.Bundle`.
 
 ## Purpose
 
 `internal/adapters/weatherapi` fetches normalized weather data from one
-configured weather API endpoint and assembles a `forecast.Bundle`.
+configured Weather API endpoint and assembles the bundle consumed by forecast
+derivation and briefing builders.
 
-## Inputs and Outputs
+## Inputs And Outputs
 
-Input:
+Inputs:
 
-- `config.Config` with `weather_api.base_url`, `format`, `units`, `timezone`,
-  `precision`, timeout, and missing-source policy.
+- `config.Config` with Weather API URL, timeout, format, units, timezone,
+  precision, and missing-source policy
+- HTTP responses using the Weather API `data` envelope
 
-Output:
+Outputs:
 
-- `forecast.Bundle` containing observation, current conditions, hourly forecast,
-  narrative forecast, alerts, discussion, stub source slots, provenance, and
-  source warnings.
+- `forecast.Bundle` with observation, current conditions, hourly forecast,
+  narrative forecast, active alerts, discussion, source records, and source
+  warnings
+- stub source records for daily forecast and weather story source slots
+- optional saved bundle JSON through app fetch helpers
 
 ## Boundaries
 
-- The adapter performs HTTP calls and decoding only.
-- Forecast derivation, daypart grouping, report periods, report rendering, and
-  `scriptorium` execution are outside this boundary.
-- Hourly forecast data is required. Other missing or malformed source sections
-  use the configured missing-source policy.
+- The adapter owns HTTP calls, response-envelope handling, source hashing, and
+  decoding into internal bundle types.
+- It does not derive dayparts, resolve report periods, build briefings, compare
+  snapshots, write report state, or invoke Scriptorium.
 
-## External Adapter
+## Config Fields Used
 
-The adapter calls:
+- `weather_api.base_url`
+- `weather_api.timeout`
+- `weather_api.format`
+- `weather_api.units`
+- `weather_api.timezone`
+- `weather_api.precision`
+- `missing_source.default`
+- `missing_source.sources`
 
-- `/observations`
-- `/conditions/current`
-- `/forecast/hourly`
-- `/forecast/narrative`
-- `/alerts/active`
-- `/discussion`
+## External Adapters Used
 
-Forecast routes use the full-product endpoints, not day-slice endpoints.
+- Weather API HTTP service
 
-## State
+See [Weather API integration](../integrations/weatherapi.md) for the external
+contract used by this project.
 
-`app.FetchAndSaveBundle` can save an inspectable bundle JSON file using an
-atomic rename. No report state, snapshots, or prompt input packages are written
-yet.
+## State Or Manifest Behavior
+
+The adapter records source name, endpoint, query, fetch time, source timestamps
+when available, SHA-256 hash over compact raw `data` JSON, missing status, and
+source warnings. `app.FetchAndSaveBundle` can write bundle JSON atomically for
+inspection.
+
+## Skip And Resume Behavior
+
+No resume behavior. Optional missing or malformed sources may be omitted,
+warned, or treated as errors according to missing-source policy. Hourly forecast
+data is required and cannot be skipped.
 
 ## Failure Behavior
 
-- HTTP and envelope decode failures return actionable errors with endpoint
-  context.
-- Missing hourly data fails the fetch.
-- Missing or malformed optional sources follow `error`, `warn`, or `none`.
-- Source identity uses SHA-256 over compacted raw `data` JSON.
+- Missing or invalid `weather_api.base_url` prevents client construction.
+- HTTP errors, response read failures, and envelope decode failures include
+  endpoint context.
+- Missing hourly data or hourly forecasts with no periods fail bundle fetch.
+- Optional and stub sources follow missing-source policy.
 
 ## Tests
 
@@ -65,5 +80,6 @@ Inspect:
 ## Invariants
 
 - Weather facts come from normalized source data.
-- External API details stay inside `internal/adapters/weatherapi`.
-- Source provenance and warnings remain inspectable for later briefing builders.
+- Full hourly and narrative products are fetched; Go owns report-period
+  selection.
+- Source provenance and warnings remain inspectable downstream.