103 lines
2.9 KiB
Markdown
103 lines
2.9 KiB
Markdown
# Module Contract Internals
|
|
|
|
This document describes the module contract in `internal/module`.
|
|
|
|
## Purpose
|
|
|
|
`internal/module` defines the shared identifiers and data envelopes used for
|
|
prompt-facing modules. Report definitions use module IDs for composition,
|
|
module builders produce outputs with stanza names, prompt input packages consume
|
|
snapshots, and Recent Changes compares snapshot stanzas.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- ordered `module.ConfigItem` values from report definitions or config
|
|
overrides
|
|
- `module.Output` values produced by module builders
|
|
|
|
Outputs:
|
|
|
|
- stable `module.ID` constants
|
|
- typed option structs for registered modules
|
|
- `module.Snapshot` with schema version `weatherreporter.modules.v1`
|
|
- ordered snapshot outputs with module ID, stanza name, and typed value
|
|
- typed stanza lookup through `module.StanzaValue`
|
|
|
|
## Registered Module IDs
|
|
|
|
The registry recognizes these IDs:
|
|
|
|
- `metadata`
|
|
- `current_conditions`
|
|
- `derived_daily_summary`
|
|
- `derived_daypart_summaries`
|
|
- `hourly_table`
|
|
- `precip_timing`
|
|
- `alert_digest`
|
|
- `area_forecast_discussion`
|
|
- `weather_story`
|
|
- `forecast_delta`
|
|
- `outdoor_windows`
|
|
- `tomorrow_planning`
|
|
- `weekend_planning`
|
|
- `storm_window_summary`
|
|
|
|
Modules with builders emit stanzas into module snapshots. Registered modules
|
|
without builders are valid composition entries but do not emit snapshot stanzas.
|
|
That keeps report composition declarations centralized while limiting prompt
|
|
packages to data the application builds.
|
|
|
|
## Options
|
|
|
|
Most modules use an empty options struct. `area_forecast_discussion` accepts:
|
|
|
|
```yaml
|
|
sections:
|
|
- product
|
|
- key_messages
|
|
- short_term
|
|
- long_term
|
|
```
|
|
|
|
An omitted or empty `sections` list includes all available discussion sections.
|
|
Invalid option shapes fail during config normalization or composition
|
|
validation.
|
|
|
|
## Boundaries
|
|
|
|
- This package owns module identifiers, config item envelopes, output
|
|
envelopes, snapshot validation, and typed stanza lookup.
|
|
- It does not define report IDs, execute builders, fetch weather data, derive
|
|
forecast facts, write state, or invoke Scriptorium.
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
`module.Snapshot` values are persisted by `internal/state` as JSON. Snapshot
|
|
validation rejects missing schema version, missing module IDs, missing stanza
|
|
names, duplicate module outputs, and duplicate stanza names while preserving
|
|
output order.
|
|
|
|
## Failure Behavior
|
|
|
|
- Snapshot construction fails for duplicate module outputs or duplicate stanza
|
|
names.
|
|
- Typed stanza lookup returns `found=false` for missing stanzas.
|
|
- Typed stanza lookup wraps JSON marshal/decode failures with stanza context.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/module/module_test.go`
|
|
- `internal/briefing/modules_test.go`
|
|
- `internal/report/period_test.go`
|
|
|
|
## Invariants
|
|
|
|
- `internal/module` does not import `internal/report`.
|
|
- Module IDs are stable strings.
|
|
- Each emitted module output has exactly one stanza name and one typed value.
|
|
- Snapshot output order is caller-owned and preserved.
|