3.5 KiB
Module Contract Internals
internal/module defines the 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 and
briefing.
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 and validates the ordered in-memory snapshot. Its JSON
representation carries a package-owned schema marker, 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. Accepted typed option pointers are
canonicalized to the declared value type before a module builder receives them.
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.
Verification and invariants
Focused tests cover snapshot validation and order, typed stanza lookup, and prompt-value fallback:
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.