68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# 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. 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](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.
|