weatherreporter/docs/internal/briefing.md

Module Builder Internals

internal/briefing builds typed module outputs from resolved report context, collected facts, and derived facts. It owns the module registry, including module support, fact requirements, option types, missing-data policy, builders, and prompt-export hooks. It does not collect data, derive periods, write a snapshot, construct YAML, invoke Promptkit, or render a report.

Registry and construction

Every ModuleDefinition declares an ID, stanza name, default option value, required collected and derived facts, supported report IDs, missing-data behavior, duplicate policy, builder, and optional prompt exporter.

BuildModule first verifies the requested module, report compatibility, and option shape. It then applies the declared missing-data behavior:

• omit returns no output for unavailable optional facts;
• error returns the missing fact requirements; and
• empty allows the builder to emit an explicit checked-empty value.

Unsupported warn behavior, missing builders, duplicate registry IDs or stanza names, output ID or stanza mismatches, and exporter failures all return errors with module context. A successful builder gets a pass-through prompt value unless its definition supplies an exporter.

Built value families

Source-oriented builders shape report metadata, current conditions, narrative and hourly forecasts, alert digest, SPC outlooks and discussion, area forecast discussion, and weather story. Derived builders shape daily and daypart summaries, precipitation timing, outdoor windows, and the report-specific Daily, Today, and Tomorrow planning values.

The module registry preserves rich values for templates and snapshots while curating prompt exports where needed. In particular, source warnings are a metadata summary, checked-empty alerts and SPC outlooks remain distinct from missing sources, and prompt-safe SPC values omit geometry and other template-only or source details. The complete module composition is in module internals; fact derivation is in fact contracts.

area_forecast_discussion accepts an optional typed section filter. Planning modules are report-specific: daily_planning supports Daily, today_planning supports Today, and tomorrow_planning supports Tomorrow.

Missing data and boundaries

Optional current conditions, narrative products, discussions, and weather stories may be omitted. Required derived modules fail when their declared facts are unavailable. Empty alert and outlook runs can still produce checked-empty modules. SPC discussion is omitted unless a retained categorical outlook meets the package's severity criterion and matching discussion text exists.

Effective units, timezone, and location context arrive in ModuleContext from configuration and resolved report metadata. Field defaults are owned by configuration, and prompt-package layout is owned by prompt input.

Verification and invariants

Focused tests cover source and derived values, registry validation, option handling, prompt exporters, support rules, and missing-data behavior:

go test ./internal/briefing

Builders emit structured facts, never report prose. The app collects their outputs into an in-memory module snapshot for prompt input and rendering.