4.7 KiB
Report Registry Internals
This document describes report identity, valid-period resolution, batch
membership, output naming, artifact grouping, and comparison declarations in
internal/report.
Purpose
internal/report is the canonical source for report definitions. App, state,
module building, and CLI wiring consume resolved definitions instead of owning
report identity policy themselves.
Definition Fields
Each report definition declares:
- report ID and display name
- Scriptorium prompt ID
- generation mode
- valid-period resolver
- comparison strategy
- managed artifact group
- batch output copy filename
- generated-report eligibility
- prior-report compatibility list
- morning or evening batch membership
- default ordered module composition
Markdown report definitions use the scriptorium_markdown generation mode.
Their template and structured-text schema identifiers are empty. Hourly Report
declares generated_text_template with template ID hourly and schema ID
hourly; the app uses those identifiers to validate generated text and render
the embedded hourly template.
Reports
| Report | ID | Prompt | Generation mode | Artifact group | Batch copy | Prior compatibility |
|---|---|---|---|---|---|---|
| Daily Today | daily_today |
weather.daily_report |
scriptorium_markdown |
daily |
daily.md |
Daily Today, Daily Tomorrow |
| Daily Tomorrow | daily_tomorrow |
weather.daily_report |
scriptorium_markdown |
daily |
tomorrow.md |
Daily Today, Daily Tomorrow |
| Hourly Report | hourly |
weather.hourly_generated_text |
generated_text_template |
hourly |
hourly.md |
Hourly Report |
| 3-Day Outlook | three_day |
weather.three_day_outlook |
scriptorium_markdown |
three-day |
three-day.md |
3-Day Outlook |
| Weekend Outlook | weekend |
weather.weekend_outlook |
scriptorium_markdown |
weekend |
weekend.md |
Weekend Outlook |
| Storm Report | storm |
weather.storm_report |
scriptorium_markdown |
storm |
storm.md |
Storm Report |
All report definitions are eligible for generation.
Valid Periods
- Daily Today covers the selected local civil day, or the current local civil day when no date override is supplied.
- Daily Tomorrow covers the next local civil day from generation time.
- Hourly Report covers the half-open six-hour period from generation time in the effective report timezone. The duration is an internal report constant, not a configuration field.
- 3-Day Outlook covers the interval from generation time through local midnight three days later.
- Weekend Outlook covers the upcoming weekend window and is not scheduled for Sunday morning batch resolution.
- Storm Report covers an explicit event window supplied by the caller.
Storm event windows can be parsed from local YYYY-MM-DDTHH:MM timestamps in
the configured timezone or RFC3339 timestamps with explicit offsets. End time
must be after start time.
Boundaries
internal/report defines report metadata and time coverage. It does not fetch
weather data, build module values, compare snapshot contents, write state,
parse CLI flags, or invoke Scriptorium.
The CLI owns public command names. The app maps those command names to report IDs, then uses the registry for report policy.
Config Fields Used
The app supplies weather_api.timezone as a loaded time.Location. Batch
output path copying uses batch output names from report definitions. Report
module overrides can use the hourly key for Hourly Report.
Batch Membership
Morning batches include Daily Today, 3-Day Outlook, and Weekend Outlook except on Sunday. Evening batches include Daily Tomorrow. Hourly Report is not part of a scheduled batch.
State And App Usage
- State paths use
ArtifactGroup. - Batch output copies use
BatchOutputName. - Generation checks
Generated. - Module composition defaults use
Modules. - Prior lookup checks
CompatiblePriorIDsand the comparison strategy. - RunIDs include the resolved report ID.
Failure Behavior
- Unknown report IDs and batch names return actionable errors.
- Weekend Outlook resolution returns an error when resolved directly on Sunday.
- Storm Report resolution requires start and end, with end after start.
Tests
Inspect:
internal/report/period_test.gointernal/app/app_test.gointernal/cli/root_test.go
Invariants
- Report selection goes through the registry.
- Daily Today and Daily Tomorrow both use
weather.daily_report. - Valid periods are half-open intervals independent of rendered report text.
- Artifact grouping, batch output filenames, generated-report eligibility, default module composition, comparison compatibility, and comparison strategy are declared by report definition.