102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# Module Builder Internals
|
|
|
|
This document describes module builder behavior in `internal/briefing`.
|
|
|
|
## Purpose
|
|
|
|
`internal/briefing` turns report metadata, collected weather data, and derived
|
|
forecast facts into prompt-facing module outputs. The package also owns the
|
|
module registry used to validate report composition and config overrides.
|
|
|
|
Module outputs are structured prompt inputs. They are not rendered report prose
|
|
and they are not persisted by this package.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- resolved report definition, generation time, timezone, and valid period
|
|
- collected facts built from `weatherdata.Bundle`
|
|
- derived daily, daypart, precipitation, alert, and storm-window facts where
|
|
required
|
|
- configured units, timezone, and descriptive location context
|
|
- typed module options from report defaults or config overrides
|
|
|
|
Outputs:
|
|
|
|
- `ModuleDefinition` values with module ID, stanza name, option type,
|
|
supported reports, fact requirements, missing-data behavior, and builder
|
|
- `module.Output` values for source-oriented stanzas:
|
|
`metadata`, `current_conditions`, `alert_digest`,
|
|
`area_forecast_discussion`, and `weather_story`
|
|
- `module.Output` values for derived stanzas:
|
|
`derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
|
|
`outdoor_windows`, and `tomorrow_planning`
|
|
|
|
The registry also contains accepted composition entries for modules that do not
|
|
emit stanzas until a builder exists. App orchestration skips those entries when
|
|
constructing snapshots.
|
|
|
|
## Boundaries
|
|
|
|
- This package selects and shapes already-collected weather facts for prompts.
|
|
- It validates module composition against report compatibility and option
|
|
types.
|
|
- It does not fetch weather data, compare prior snapshots, write module
|
|
snapshots, build YAML data packages, invoke Scriptorium, or write workflow
|
|
metadata.
|
|
|
|
## Config Fields Used
|
|
|
|
The app layer passes effective units, timezone, and location context into the
|
|
module context. `internal/facts` consumes daypart configuration before module
|
|
builders run. Configured `location` values are prompt context only; Weather API
|
|
`sourceLocationId` and `sourceLocation` remain source provenance.
|
|
|
|
`area_forecast_discussion` uses optional `sections` configuration to include a
|
|
subset of discussion fields.
|
|
|
|
## External Adapters Used
|
|
|
|
None directly.
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
None. `internal/app` collects module outputs into a `module.Snapshot`, and
|
|
`internal/state` persists that snapshot.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
None. Builders either emit a module output, omit optional unavailable data, or
|
|
return an error for invalid required inputs.
|
|
|
|
## Failure Behavior
|
|
|
|
- Required derived modules return errors when their dependent facts are not
|
|
available.
|
|
- Module registry construction rejects duplicate module IDs and duplicate
|
|
stanza names.
|
|
- Composition validation rejects unknown modules, duplicate modules,
|
|
incompatible report/module combinations, duplicate stanza names, and invalid
|
|
option shapes.
|
|
- Source-oriented module builders omit missing optional current conditions,
|
|
forecast discussion, and weather story stanzas.
|
|
- Alert digest output distinguishes checked empty alert data from missing alert
|
|
source data.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/briefing/base_modules_test.go`
|
|
- `internal/briefing/derived_modules_test.go`
|
|
- `internal/briefing/modules_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Module outputs contain structured weather facts and source context.
|
|
- Common metadata includes RunID, report ID, prompt ID, valid period, source
|
|
provenance, source hashes, source warnings, and configured prompt location.
|
|
- Prompt input packaging and Scriptorium execution remain outside this package.
|