# 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`, `narrative_forecast`, `hourly_forecast`,
  `alert_digest`, `spc_convective_outlooks`,
  `area_forecast_discussion`, `spc_convective_discussion`, and
  `weather_story`
- `module.Output` values for derived stanzas:
  `derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
  `outdoor_windows`, and `tomorrow_planning`

Every registered composition entry has a builder. Unknown or unimplemented
module IDs fail validation instead of being skipped.

Prompt-facing module values use local, human-readable date and time labels
where the LLM is expected to reason about report content. Canonical timestamps
remain in report metadata, source provenance, and integration artifacts.

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

`spc_convective_outlooks` uses collected SPC run metadata and derived
report-period outlooks. It emits `checked: true` for a successfully fetched
empty run, reports `outlook_count`, and includes prompt-facing outlook fields
such as risk label, `period_begins`, `period_ends`, image URL, and whether the
outlook contains the configured location. It does not emit GeoJSON geometry,
source URL, expiration time, or severity rank.

Prompt-facing module intervals use friendly local `period_begins` and
`period_ends` labels. Canonical report metadata, source provenance,
`issued_at`, `updated_at`, and point-in-time fields remain separate.

`spc_convective_discussion` uses the same derived report-period outlooks and
discussion records. It is omitted unless at least one retained categorical
outlook for the same SPC day has severity rank `3` or higher and matching
discussion text exists.

## 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.
- SPC convective outlook output distinguishes checked empty outlook data from
  missing outlook source data and omits GeoJSON geometry from prompt-facing
  fields.
- SPC convective discussion output is omitted unless a retained outlook has
  severity rank `3` or higher and matching discussion text is available.

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