70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
# 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](module.md); fact derivation is in [fact contracts](facts.md).
|
|
|
|
`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](../config.md), and prompt-package layout is owned by
|
|
[prompt input](prompt-input.md).
|
|
|
|
## Verification and invariants
|
|
|
|
Focused tests cover source and derived values, registry validation, option
|
|
handling, prompt exporters, support rules, and missing-data behavior:
|
|
|
|
```sh
|
|
go test ./internal/briefing
|
|
```
|
|
|
|
Builders emit structured facts, never report prose. The app collects their
|
|
outputs into a module snapshot, and state persists that snapshot.
|