weatherreporter/docs/internal/report-registry.md

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, public command names, config-key aliases, and batch command names. App, config, state, module building, and CLI wiring consume report-owned helpers and 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

Report-owned helpers map public command names and config keys to report IDs. The generate command names are daily, today, tomorrow, hourly, three-day, weekend, and storm. Config keys also accept selected underscore and descriptive aliases such as three_day_outlook, weekend_outlook, and storm_report.

daily resolves to the dated Daily Report ID daily. today resolves to the independent Today report ID today. reports.today is not an alias for reports.daily, and retired report keys are not supported.

Markdown report definitions use the scriptorium_markdown generation mode. Their template and structured-text schema identifiers are empty. Daily Report, Today Report, Tomorrow Report, and Hourly Report declare generated_text_template; the app uses their template and schema identifiers to validate generated text and render embedded Markdown templates.

Reports

Report	ID	Prompt	Generation mode	Artifact group	Batch copy	Prior compatibility
Daily Report	daily	weather.daily_generated_text	generated_text_template	daily	daily.md	Daily Report
Today Report	today	weather.today_generated_text	generated_text_template	today	today.md	Today Report
Tomorrow Report	tomorrow	weather.tomorrow_generated_text	generated_text_template	tomorrow	tomorrow.md	Tomorrow Report
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 Report covers the selected local civil day and requires an explicit date.
• Today Report covers the selected local civil day, or the current local civil day when no date override is supplied.
• Tomorrow Report 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, public report names, batch command names, 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 parses flags and command structure, then uses report-owned helpers for report and batch command names. Config loading uses report-owned helpers for report override keys.

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 short keys such as daily, today, tomorrow, and hourly, or descriptive names such as three_day_outlook.

Batch Membership

Morning batches include Today Report, 3-Day Outlook, and Weekend Outlook except on Sunday. Evening batches include Tomorrow Report. Daily Report and Hourly Report are 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 CompatiblePriorIDs and 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.go
• internal/app/app_test.go
• internal/cli/root_test.go

Invariants

• Report selection goes through the registry.
• Public command names, config-key aliases, and batch command names are owned by internal/report.
• Direct Markdown reports have empty template and generated-text schema IDs.
• Generated-text-template reports declare prompt, template, and schema IDs in their report definition.
• 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.