# Module Contract Internals

`internal/module` defines the stable envelope between report composition,
module builders, in-memory snapshots, templates, and prompt packages. It
does not define a report, execute a builder, or choose prompt-export policy;
those responsibilities belong to [report registry](report-registry.md) and
[briefing](briefing.md).

## Outputs and snapshots

Each `Output` has a module ID, stanza name, rich `Value`, and runtime-only
`PromptValue`. `DataPackageValue` returns the prompt value when present and
otherwise the rich value. This permits custom prompt exports without shrinking
the template value.

`NewSnapshot` builds the ordered `weatherreporter.modules.v1` snapshot and
validates it. Its JSON representation contains IDs, stanza names, and rich values only;
`PromptValue` is deliberately excluded. `StanzaValue` decodes a named rich
stanza into a caller-supplied type, reporting a missing stanza separately from
a decoding error.

Snapshots reject missing schema versions, empty IDs or stanza names, and
duplicate IDs or stanza names. Output order is caller-owned and preserved.

## Registered IDs and default composition

The registered IDs are `metadata`, `current_conditions`,
`narrative_forecast`, `hourly_forecast`, `derived_daily_summary`,
`derived_daypart_summaries`, `precip_timing`, `alert_digest`,
`spc_convective_outlooks`, `area_forecast_discussion`,
`spc_convective_discussion`, `weather_story`, `outdoor_windows`,
`today_planning`, `tomorrow_planning`, and `daily_planning`.

The registry declares these ordered default compositions:

| Report | Ordered modules |
| --- | --- |
| Daily | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD (long term), SPC discussion, weather story, outdoor windows, daily planning, hourly forecast |
| Today | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, hourly forecast, today planning |
| Tomorrow | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, tomorrow planning, hourly forecast |
| Hourly | metadata, current conditions, hourly forecast, precipitation timing, alert digest, SPC outlooks, AFD (key messages and short term), SPC discussion, weather story |

The only non-empty default option is the AFD section selection. It accepts a
`sections` list; omitted or empty selects all available sections. Report
definitions may narrow it as shown above. Option shape and report compatibility
are validated by the briefing registry.

## Rich and prompt-facing values

Rich values remain available to module snapshots and render contexts.
Briefing attaches custom prompt exports only for current conditions, hourly
forecast, and derived daypart summaries; all other current builders use
pass-through values. The prompt package owns how exported stanzas are grouped
and serialized; see [prompt input](prompt-input.md).

## Verification and invariants

Focused tests cover snapshot validation and order, typed stanza lookup, and
prompt-value fallback:

```sh
go test ./internal/module
```

Module IDs and stanza names are stable, every emitted output has one of each,
and this package never imports the report registry.