# Report Registry Internals

This document describes report identity, valid-period resolution, batch
membership, and comparison declarations in `internal/report`.

## Purpose

`internal/report` centralizes report definitions so report IDs, prompt IDs,
artifact groups, batch output names, generated-report eligibility, comparison
compatibility, comparison strategies, and valid periods are declared in one
package.

## Inputs And Outputs

Inputs:

- report ID or batch name
- generation time
- timezone
- optional Daily date override
- optional Storm Report start and end times

Outputs:

- `report.Resolved` values with definition metadata and half-open valid periods
- `report.Metadata` values used by briefing and persisted metadata builders

## Boundaries

- This package defines report identity and time coverage only.
- It does not fetch weather data, build briefings, compare snapshots, write
  state, parse CLI flags, or invoke Scriptorium.

## 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.

## External Adapters Used

None.

## State Or Manifest Behavior

None directly. Resolved metadata contributes RunID, report ID, prompt ID,
generation time, timezone, and valid period to later briefing and state
metadata. Artifact groups declared by report definitions are used by state path
construction.

## Skip And Resume Behavior

No resume behavior. Morning batch resolution skips Weekend Outlook on Sunday.

## Failure Behavior

- Unknown reports 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.
- 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,
  comparison compatibility, and comparison strategy are declared by report
  definition.