# Module Builder Internals

`internal/briefing` builds typed module outputs from resolved report context,
collected facts, and derived facts. It owns the module registry, including
module support, fact requirements, option types, missing-data policy, builders,
and prompt-export hooks. It does not collect data, derive periods, write a
snapshot, construct YAML, invoke Promptkit, or render a report.

## Registry and construction

Every `ModuleDefinition` declares an ID, stanza name, default option value,
required collected and derived facts, supported report IDs, missing-data
behavior, duplicate policy, builder, and optional prompt exporter.

`BuildModule` first verifies the requested module, report compatibility, and
option shape. It then applies the declared missing-data behavior:

- `omit` returns no output for unavailable optional facts;
- `error` returns the missing fact requirements; and
- `empty` allows the builder to emit an explicit checked-empty value.

Unsupported `warn` behavior, missing builders, duplicate registry IDs or
stanza names, output ID or stanza mismatches, and exporter failures all return
errors with module context. A successful builder gets a pass-through prompt
value unless its definition supplies an exporter.

## Built value families

Source-oriented builders shape report metadata, current conditions, narrative
and hourly forecasts, alert digest, SPC outlooks and discussion, area forecast
discussion, and weather story. Derived builders shape daily and daypart
summaries, precipitation timing, outdoor windows, and the report-specific
Daily, Today, and Tomorrow planning values.

The module registry preserves rich values for templates and snapshots while
curating prompt exports where needed. In particular, source warnings are a
metadata summary, checked-empty alerts and SPC outlooks remain distinct from
missing sources, and prompt-safe SPC values omit geometry and other
template-only or source details. The complete module composition is in
[module internals](module.md); fact derivation is in [fact contracts](facts.md).

`area_forecast_discussion` accepts an optional typed section filter. Planning
modules are report-specific: `daily_planning` supports Daily,
`today_planning` supports Today, and `tomorrow_planning` supports Tomorrow.

## Missing data and boundaries

Optional current conditions, narrative products, discussions, and weather
stories may be omitted. Required derived modules fail when their declared facts
are unavailable. Empty alert and outlook runs can still produce checked-empty
modules. SPC discussion is omitted unless a retained categorical outlook meets
the package's severity criterion and matching discussion text exists.

Effective units, timezone, and location context arrive in `ModuleContext` from
configuration and resolved report metadata. Field defaults are owned by
[configuration](../config.md), and prompt-package layout is owned by
[prompt input](prompt-input.md).

## Verification and invariants

Focused tests cover source and derived values, registry validation, option
handling, prompt exporters, support rules, and missing-data behavior:

```sh
go test ./internal/briefing
```

Builders emit structured facts, never report prose. The app collects their
outputs into an in-memory module snapshot for prompt input and rendering.