# Weather Data Internals

This document describes Weather API ingestion into `weatherdata.Bundle`.

## Purpose

`internal/adapters/weatherapi` fetches normalized weather data from one
configured Weather API endpoint and assembles the bundle consumed by forecast
derivation and briefing builders. Briefing builders expose normalized current
conditions and weather story context when those sources are available.

## Inputs And Outputs

Inputs:

- `config.Config` with Weather API URL, timeout, format, units, timezone,
  precision, and missing-source policy
- HTTP responses using the Weather API `data` envelope

Outputs:

- `weatherdata.Bundle` with observation, current conditions, hourly forecast,
  narrative forecast, active alerts, discussion, latest weather story, source
  records, and source warnings
- stub source record for the daily forecast source slot
- optional saved bundle JSON through app fetch helpers

## Boundaries

- 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.

## Config Fields Used

- `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`

## External Adapters Used

- Weather API HTTP service

See [Weather API integration](../integrations/weatherapi.md) for the external
contract used by this project.

## 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. Successful `data: null` responses from `/alerts/active`
represent a checked empty active-alert list, not a missing source.
`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

- 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.
- Explicit `data: null` from `/alerts/active` produces an empty, non-missing
  alert run.

## Tests

Inspect:

- `internal/adapters/weatherapi/client_test.go`
- `internal/app/app_test.go`

## Invariants

- Weather facts come from normalized source data.
- Full hourly and narrative products are fetched; Go owns report-period
  selection.
- Source provenance and warnings remain inspectable downstream.