103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
# Briefing Internals
|
|
|
|
This document describes the implemented briefing package boundary.
|
|
|
|
## Purpose
|
|
|
|
`internal/briefing` builds structured report-specific briefing packages from
|
|
resolved report metadata, collected weather data, and derived forecast facts.
|
|
Briefings are curated inputs for prompt data packages, not rendered report prose.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- resolved report definition, generation time, timezone, and valid period
|
|
- `weatherdata.Bundle` with source provenance and warnings
|
|
- derived daily, period, or storm-window facts where required
|
|
- configured units, timezone, and descriptive location context
|
|
|
|
Outputs:
|
|
|
|
- `briefing.Package` with common metadata and one report-specific content
|
|
object for Daily, 3-Day, Weekend, or Storm Report
|
|
- module registry definitions for known module IDs, stanza names, option
|
|
shapes, fact requirements, report compatibility, and missing-data behavior
|
|
- source-oriented module outputs for `metadata`, `current_conditions`,
|
|
`alert_digest`, `area_forecast_discussion`, and `weather_story`
|
|
- optional `currentConditions` prompt context from normalized
|
|
`/conditions/current` data when available
|
|
- optional structured `weatherStory` context on report-specific briefing
|
|
objects when `/weatherstories/latest` is available
|
|
- optional JSON file written by `briefing.Save`
|
|
|
|
## Boundaries
|
|
|
|
- This package selects and shapes weather facts for prompts.
|
|
- It owns module registry validation, but app orchestration does not execute
|
|
modules yet.
|
|
- It does not fetch weather data, compare prior snapshots, build
|
|
`data_package` files, invoke Scriptorium, or write workflow metadata.
|
|
|
|
## Config Fields Used
|
|
|
|
The package receives configured units and timezone from the app layer. Daypart
|
|
configuration is consumed by `internal/facts` before briefing builders run.
|
|
Configured `location` values are prompt context only; Weather API
|
|
`sourceLocationId` and `sourceLocation` remain source provenance.
|
|
Current conditions are copied from the normalized `/conditions/current` bundle
|
|
source only; observation station and timestamp fields remain provenance.
|
|
|
|
## External Adapters Used
|
|
|
|
None directly.
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
`briefing.Save` writes briefing JSON atomically. Managed workspace placement is
|
|
owned by `internal/state`.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
None. Builders either return a complete briefing package or an error.
|
|
|
|
## Failure Behavior
|
|
|
|
- Daily briefing construction requires a Daily report definition and derived
|
|
daily summary.
|
|
- 3-Day briefing construction requires a 3-Day report definition and at least
|
|
one derived summary.
|
|
- Weekend briefing construction requires a Weekend report definition and at
|
|
least one derived summary.
|
|
- Storm briefing construction requires a Storm Report definition and forecast
|
|
bundle.
|
|
- Module registry construction rejects duplicate module IDs and duplicate
|
|
stanza names.
|
|
- Module composition validation rejects unknown modules, duplicate modules,
|
|
incompatible report/module combinations, and invalid typed options.
|
|
- 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.
|
|
- Save failures include path and operation context.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/briefing/daily_test.go`
|
|
- `internal/briefing/three_day_test.go`
|
|
- `internal/briefing/weekend_test.go`
|
|
- `internal/briefing/storm_test.go`
|
|
- `internal/briefing/base_modules_test.go`
|
|
- `internal/briefing/modules_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Briefings 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.
|
|
- LLM prompt input packaging and Scriptorium execution remain outside this
|
|
boundary.
|