weatherreporter/docs/internal/module.md

Module Contract Internals

This document describes the implemented module contract boundary.

Purpose

internal/module defines stable module IDs, typed configuration items, module outputs, and module snapshots. It is a shared contract imported by report definitions and module registry code.

Inputs And Outputs

Inputs:

• ordered module.ConfigItem values from report definitions
• module.Output values assembled by callers

Outputs:

• stable module.ID constants
• typed option structs for known modules
• module.Snapshot with ordered outputs and schema version
• typed stanza lookup through module.StanzaValue

Boundaries

• This package owns shared module identifiers and output envelope contracts.
• It does not define report IDs, build prompt stanzas, fetch weather data, derive facts, write state, or invoke Scriptorium.

State Or Manifest Behavior

module.Snapshot uses schema version weatherreporter.modules.v1. Snapshot validation rejects duplicate module outputs and duplicate stanza names while preserving output order.

Failure Behavior

• Snapshot validation fails when schema version, module ID, or stanza name is missing.
• Snapshot validation fails on duplicate module IDs or duplicate stanza names.
• Typed stanza lookup returns found=false for missing stanzas and 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 module output has exactly one stanza name and one typed value.
• Snapshot output order is caller-owned and preserved.