# Module Builder Internals

This document describes the implemented module builder boundary in
`internal/briefing`.

## Purpose

`internal/briefing` builds prompt-facing module values from resolved report
metadata, collected weather data, and derived forecast facts. These values are
curated prompt inputs, not rendered report prose or durable report snapshots.

## Inputs And Outputs

Inputs:

- resolved report definition, generation time, timezone, and valid period
- `weatherdata.Bundle` with source provenance and warnings
- derived daily, period, or storm-window facts where required
- configured units, timezone, and descriptive location context

Outputs:

- module registry definitions for known module IDs, stanza names, option
  shapes, fact requirements, report compatibility, and missing-data behavior
- source-oriented module outputs for `metadata`, `current_conditions`,
  `alert_digest`, `area_forecast_discussion`, and `weather_story`
- derived module outputs such as daily summaries, daypart summaries,
  precipitation timing, outdoor windows, and tomorrow planning
- optional current conditions and weather story module outputs when those
  Weather API sources are available

## Boundaries

- This package selects and shapes weather facts for prompts.
- It owns module registry validation and module builder behavior.
- It does not fetch weather data, compare prior snapshots, build
  `data_package` files, invoke Scriptorium, or write workflow metadata.

## Config Fields Used

The package receives configured units and timezone from the app layer. Daypart
configuration is consumed by `internal/facts` before module 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
source only; observation station and timestamp fields remain provenance.

## External Adapters Used

None directly.

## State Or Manifest Behavior

None. Module snapshots and prompt input data packages are persisted by
`internal/state` and composed by `internal/app`.

## Skip And Resume Behavior

None. Builders either return 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.
- Module composition validation rejects unknown modules, duplicate modules,
  incompatible report/module combinations, and invalid typed options.
- 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.
- LLM prompt input packaging and Scriptorium execution remain outside this
  boundary.