weatherreporter/docs/internal/briefing.md

# Module Builder Internals

This document describes module builder behavior in `internal/briefing`.

## Purpose

`internal/briefing` turns report metadata, collected weather data, and derived
forecast facts into prompt-facing module outputs. The package also owns the
module registry used to validate report composition and config overrides.

Module outputs are structured prompt inputs. They are not rendered report prose
and they are not persisted by this package.

## Inputs And Outputs

Inputs:

- resolved report definition, generation time, timezone, and valid period
- collected facts built from `weatherdata.Bundle`
- derived daily, daypart, precipitation, alert, and storm-window facts where
  required
- configured units, timezone, and descriptive location context
- typed module options from report defaults or config overrides

Outputs:

- `ModuleDefinition` values with module ID, stanza name, option type,
  supported reports, fact requirements, missing-data behavior, and builder
- `module.Output` values for source-oriented stanzas:
  `metadata`, `current_conditions`, `alert_digest`,
  `area_forecast_discussion`, and `weather_story`
- `module.Output` values for derived stanzas:
  `derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
  `outdoor_windows`, and `tomorrow_planning`

The registry also contains accepted composition entries for modules that do not
emit stanzas until a builder exists. App orchestration skips those entries when
constructing snapshots.

## Boundaries

- This package selects and shapes already-collected weather facts for prompts.
- It validates module composition against report compatibility and option
  types.
- It does not fetch weather data, compare prior snapshots, write module
  snapshots, build YAML data packages, invoke Scriptorium, or write workflow
  metadata.

## Config Fields Used

The app layer passes effective units, timezone, and location context into the
module context. `internal/facts` consumes daypart configuration before module
builders run. Configured `location` values are prompt context only; Weather API
`sourceLocationId` and `sourceLocation` remain source provenance.

`area_forecast_discussion` uses optional `sections` configuration to include a
subset of discussion fields.

## External Adapters Used

None directly.

## State Or Manifest Behavior

None. `internal/app` collects module outputs into a `module.Snapshot`, and
`internal/state` persists that snapshot.

## Skip And Resume Behavior

None. Builders either emit a module output, omit optional unavailable data, or
return an error for invalid required inputs.

## Failure Behavior

- Required derived modules return errors when their dependent facts are not
  available.
- Module registry construction rejects duplicate module IDs and duplicate
  stanza names.
- Composition validation rejects unknown modules, duplicate modules,
  incompatible report/module combinations, duplicate stanza names, and invalid
  option shapes.
- Source-oriented module builders omit missing optional current conditions,
  forecast discussion, and weather story stanzas.
- Alert digest output distinguishes checked empty alert data from missing alert
  source data.

## Tests

Inspect:

- `internal/briefing/base_modules_test.go`
- `internal/briefing/derived_modules_test.go`
- `internal/briefing/modules_test.go`
- `internal/app/app_test.go`

## Invariants

- Module outputs contain structured weather facts and source context.
- Common metadata includes RunID, report ID, prompt ID, valid period, source
  provenance, source hashes, source warnings, and configured prompt location.
- Prompt input packaging and Scriptorium execution remain outside this package.