Add module contracts and registry validation

docs/internal/module.md

@@ -0,0 +1,58 @@
+# 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 briefing 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 briefing 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.