weatherreporter/docs/internal/module.md

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
• narrative_forecast
• hourly_forecast
• derived_daily_summary
• derived_daypart_summaries
• precip_timing
• alert_digest
• spc_convective_outlooks
• area_forecast_discussion
• weather_story
• outdoor_windows
• tomorrow_planning

Every registered module has a builder. Report composition entries that refer to unknown or unimplemented module IDs fail validation instead of being skipped.

The package also defines the spc_convective_discussion ID and empty option struct for the collected contract. It is not a registered module in the briefing registry until its builder exists.

Options

Most modules use an empty options struct. area_forecast_discussion accepts:

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.