eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Reconcile internal implementation guides

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-13 04:25:40 +00:00
parent b985c5faac
commit 88fde0df7f
4 changed files with 103 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/internal/report-registry.md
View File

@@ -1,34 +1,37 @@
# Report Registry Internals
`internal/report` owns report identities, valid-period resolution, exact prompt identity and version, output names, default module composition, and Distributor path declarations. Public command syntax belongs in the [CLI reference](../cli.md); configuration aliases and overrides belong in the [configuration reference](../config.md).
`internal/report` owns the in-process registry of report identities and the
resolution of a report's valid period. Command names and configuration aliases
belong to the [CLI reference](../cli.md) and [configuration
reference](../config.md), respectively.
## Definitions And Resolution
## Registry And Resolution
Each `Definition` declares a stable ID and display name, prompt ID and version, template and generated-text schema IDs, valid-period resolver, default output name, Distributor path templates, module list, and fixed batch eligibility. `Resolved` combines a definition with one valid period and run identity.
`DefaultRegistry` supplies the maintained definitions. `Lookup` returns a
definition by its internal ID, while `Resolve` combines it with a request time,
location, and optional date to produce `Resolved`. The result carries the
definition, generation time, timezone, and resolved valid period; its metadata
and output-name helpers keep derived identity values consistent for callers.
| Report ID | Prompt version | Default profile | Period policy | Fixed batch flag | Default output |
| --- | --- | --- | --- | --- | --- |
| `daily` | `2.0.0` | `weather-balanced` | Explicit local civil day | Dynamic Daily inclusion is app-owned | `daily-YYYY-MM-DD.md` |
| `today` | `2.0.0` | `weather-balanced` | Selected or current local civil day | Morning | `today.md` |
| `tomorrow` | `2.0.0` | `weather-balanced` | Next local civil day | Evening | `tomorrow.md` |
| `hourly` | `2.0.0` | `weather-light` | Rolling six-hour interval | — | `hourly.md` |
Definitions carry the internal collaborators needed downstream: prompt and
template identity, module configuration, output naming, Distributor path
templates, and fixed batch eligibility. The external prompt contract is owned
by the [Promptkit integration guide](../integrations/promptkit.md), template
surface by the [report template guide](../templates.md), and published
Distributor paths by the [Distributor bundle guide](../integrations/distributor/pkg-bundle.md).
Daily derives its filename and run identity from the resolved valid-period start
in the effective timezone, so multiple Daily items have distinct destinations
and identifiers. Exact template fields and schema assets belong to [report
templates](../templates.md) and [generated-text internals](generatedtext.md).
Prompt assets own default profile selection; the registry stores no provider
setting.
`WithModuleOverrides` returns an independently cloned registry with replacement
module configuration for recognized report IDs. The application owns batch
planning and data-dependent inclusion; see [app orchestration
internals](app-orchestration.md).
## Collaborators And Boundaries
The registry never collects weather data, parses CLI flags, writes output,
executes Promptkit, or delivers a report.
`DefaultRegistry`, `Lookup`, `Resolve`, and report-name helpers prevent callers from duplicating report identity rules. Registry overrides clone a recognized definition and replace its module list. `DistributorPathTemplates` are consumed by app orchestration; their rendered external bundle-path contract is documented in the [Distributor bundle guide](../integrations/distributor/pkg-bundle.md).
## Verification
`morning` and `evening` are registry-owned batch names. Fixed flags declare Today and Tomorrow eligibility; app orchestration determines data-dependent Daily membership and the actual batch plan.
The registry never collects weather data, parses CLI flags, writes output, executes Promptkit, or delivers a report.
Focused tests cover definition completeness, command and alias lookup, period resolution, run IDs, output names, composition defaults, and override validation:
Focused tests protect retained report definitions, period resolution, Daily
run-ID disambiguation, and rejection of retired command or configuration names:
```sh
go test ./internal/report