Prepare reports for Promptkit migration

This commit is contained in:
2026-07-31 03:53:47 +00:00
parent 2e0fb65a8b
commit d5fcbfd20c
87 changed files with 2223 additions and 3382 deletions

View File

@@ -12,8 +12,8 @@ inspection requests. Generation and batch requests may supply collector,
renderer, store, and notifier implementations for tests; production defaults
use the focused packages.
A report result contains the module snapshot, prompt package, available
Scriptorium results, generated-text artifacts when used, report and metadata
A report result contains the module snapshot, prompt package, Scriptorium
results, generated-text artifacts, report and metadata
paths, prior snapshot, Recent Changes, and notification information. A batch
result contains aggregate counts, per-report outcomes, and an optional batch
notification. Inspection returns persisted values only.
@@ -39,17 +39,17 @@ ordered work:
snapshot and calculate Recent Changes.
3. Build and save the prompt data package, run Scriptorium render preflight,
save any preflight result, and save initial metadata.
4. Produce managed Markdown according to the report generation mode.
4. Run structured Scriptorium generation, validate and save generated text,
build and save a render context, and render the managed Markdown template.
5. Optionally make an output copy, save final metadata, optionally notify
Distributor from the managed report path, and save metadata again when a
notification path is produced.
Direct-Markdown reports prepare the managed report and invoke the Scriptorium
run boundary. Generated-text-template reports look up their catalog definition,
run structured Scriptorium output to the raw artifact, preserve any structured
run result, validate and save generated text, build and save a render context,
then render the embedded Markdown template. Schema, template, and subprocess
details remain in their [generated-text](generatedtext.md),
Every report looks up its catalog definition, runs structured Scriptorium
output to the raw artifact, preserves the structured run result, validates and
saves generated text, builds and saves a render context, then renders the
embedded Markdown template. Schema, template, and subprocess details remain in
their [generated-text](generatedtext.md),
[report-template](reporttemplate.md), and [Scriptorium adapter](scriptorium-adapter.md)
owners.
@@ -104,7 +104,7 @@ Focused tests are in `internal/app/app_test.go` and
- A report uses one explicit normalized collection throughout its generation.
- Render preflight precedes report generation.
- Recent Changes compare structured module snapshots.
- Generated-text reports render from a validated typed context, never directly
from a raw prompt package.
- Reports render from a validated typed context, never directly from a raw
prompt package.
- Only managed Markdown reports are notification sources; output copies are
never uploaded.

View File

@@ -25,19 +25,14 @@ requires a change between its low, possible, likely, and high categories.
| Comparator | Required snapshot data | Compared values |
| --- | --- | --- |
| `CompareDaily` | `derived_daily_summary`, `derived_daypart_summaries` | Low and high temperature, daily precipitation probability and timing, peak gust, alerts, and aggregate indicators |
| `CompareThreeDay` | `derived_daypart_summaries` | Per-day temperatures, precipitation probability and timing, peak gust, indicators, and added or removed outlook days |
| `CompareWeekend` | `derived_daypart_summaries` | The three-day values with weekend-prefixed change types |
For daily comparison, `alert_digest` and `precip_timing` are optional: alerts
are compared when present, and timing is compared only when both snapshots
contain it. The multi-day comparators build their day map from daypart
summaries. A missing or added day becomes a dedicated change rather than a
comparison against invented data.
contain it.
The application selects a comparator only after state lookup establishes a
compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator;
Three-day and Weekend use their named comparators. Other report types, such as
Storm, produce no Recent Changes list.
compatible prior snapshot. Daily, Today, and Tomorrow use the daily comparator.
Hourly reports do not produce a Recent Changes list.
## Missing data and failures
@@ -51,8 +46,8 @@ behavior. It does not decide report compatibility or retain snapshots.
## Verification and invariants
Focused tests cover the daily, three-day, and weekend strategies, threshold
boundaries, indicator and alert changes, and missing required stanzas:
Focused tests cover the daily strategy, threshold boundaries, indicator and
alert changes, and missing required stanzas:
```sh
go test ./internal/changes

View File

@@ -33,10 +33,8 @@ Report identity controls the summary shape:
| --- | --- |
| Hourly | Rolling-period selections and precipitation timing; no daily or daypart summary |
| Daily, Today, Tomorrow | One local civil-day summary and its dayparts |
| Three-day, Weekend | One clipped daily summary for each overlapping local day |
| Storm | One summary for the explicit report window |
`DaypartSummaries` is collected from the resulting daily or storm summaries.
`DaypartSummaries` is collected from the resulting daily summaries.
The detailed grouping, daypart-window, and alert rules are owned by
[forecast derivation](forecast-derivation.md).
@@ -55,8 +53,7 @@ not access the CLI, filesystem, subprocesses, or network.
## Verification and invariants
Focused tests cover collected-fact separation, report-period selection,
hourly and storm behavior, daily and partial-day summaries, and convective
outlook selection:
hourly behavior, daily summaries, and convective outlook selection:
```sh
go test ./internal/facts

View File

@@ -8,12 +8,12 @@ maintainer-facing context fields belong to [report templates](../templates.md).
## Catalog and validation
Only the Daily, Today, Tomorrow, and Hourly report definitions use the
generated-text-template mode. `LookupDefinition` rejects a direct-Markdown
definition, unknown schema or template IDs, and unsupported schema/template
pairs before the run begins. A handler validates raw JSON, returns a typed
value and canonical normalized JSON, loads its schema, builds a render context,
and renders through `internal/reporttemplate`.
The Daily, Today, Tomorrow, and Hourly report definitions each use structured
generated text. `LookupDefinition` rejects unknown schema or template IDs and
unsupported schema/template pairs before the run begins. A handler validates raw JSON, returns a typed
value and canonical normalized JSON, loads its canonical schema through
`internal/promptassets`, builds a render context, and renders through
`internal/reporttemplate`.
Daily, Today, and Tomorrow use a day-style value with required trimmed summary
and one or more nonblank discussion paragraphs. Hourly requires trimmed summary
@@ -47,5 +47,5 @@ go test ./internal/generatedtext
```
Generated text supplies prose slots only; deterministic weather facts remain in
module and fact values. Every generated-text definition must resolve to exactly
one supported catalog pair.
module and fact values. Every report definition must resolve to exactly one
supported catalog pair.

View File

@@ -39,8 +39,6 @@ The registry declares these ordered default compositions:
| Today | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, hourly forecast, today planning |
| Tomorrow | metadata, current conditions, narrative forecast, daily summary, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows, tomorrow planning, hourly forecast |
| Hourly | metadata, current conditions, hourly forecast, precipitation timing, alert digest, SPC outlooks, AFD (key messages and short term), SPC discussion, weather story |
| Three-day and Weekend | metadata, current conditions, daypart summaries, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story, outdoor windows |
| Storm | metadata, current conditions, precipitation timing, alert digest, SPC outlooks, AFD, SPC discussion, weather story |
The only non-empty default option is the AFD section selection. It accepts a
`sections` list; omitted or empty selects all available sections. Report

View File

@@ -1,7 +1,7 @@
# Report Registry Internals
`internal/report` owns the registry of report identities and the data declared
for each one: resolution, generation mode, prompt identity, comparison policy,
for each one: resolution, prompt identity and version, comparison policy,
artifact group, output-copy name, default module composition, and Distributor
path declarations. The public command syntax is owned by the
[CLI reference](../cli.md); configuration aliases and overrides are owned by
@@ -10,34 +10,28 @@ the [configuration reference](../config.md).
## Definitions and resolution
Each `Definition` declares a stable ID and display name, prompt ID, generation
mode, optional template and generated-text schema IDs, valid-period resolver,
version, template and generated-text schema IDs, valid-period resolver,
comparison strategy, artifact group, batch-copy filename, Distributor path
templates, generation eligibility, compatible prior IDs, default modules, and
batch eligibility flags. `Resolved` combines that definition with the valid
period and run metadata for one invocation.
| Report ID | Mode | Period policy | Comparison | Registry batch flag | Output copy |
| Report ID | Prompt version | Period policy | Comparison | Registry batch flag | Output copy |
| --- | --- | --- | --- | --- | --- |
| `daily` | Generated text + template | Explicit local civil day | Same valid date | Dynamic Daily inclusion is app-owned | `daily.md` |
| `today` | Generated text + template | Selected or current local civil day | Same valid date | Morning | `today.md` |
| `tomorrow` | Generated text + template | Next local civil day | Same valid date | Evening | `tomorrow.md` |
| `hourly` | Generated text + template | Rolling six-hour interval | Rolling window | — | `hourly.md` |
| `three_day` | Scriptorium Markdown | Generation time through the third following local midnight | Same valid date | Morning | `three-day.md` |
| `weekend` | Scriptorium Markdown | Upcoming weekend window | Weekend window | Morning | `weekend.md` |
| `storm` | Scriptorium Markdown | Caller-supplied event window | Explicit window | — | `storm.md` |
| `daily` | `1.0.0` | Explicit local civil day | Same valid date | Dynamic Daily inclusion is app-owned | `daily.md` |
| `today` | `1.0.0` | Selected or current local civil day | Same valid date | Morning | `today.md` |
| `tomorrow` | `1.0.0` | Next local civil day | Same valid date | Evening | `tomorrow.md` |
| `hourly` | `1.0.0` | Rolling six-hour interval | Rolling window | — | `hourly.md` |
The four generated-text reports pair their report ID with matching template and
schema IDs. The three direct-Markdown reports leave both IDs empty. Exact
template fields and schema assets belong to [report templates](../templates.md)
Each report pairs its ID and prompt version with matching template and schema
IDs. Exact template fields and schema assets belong to [report templates](../templates.md)
and [generated-text internals](generatedtext.md).
All valid periods are half-open. Storm accepts local `YYYY-MM-DDTHH:MM` values
in the effective report timezone or offset-bearing RFC3339 values; its end
must follow its start. Resolving Weekend directly on Sunday is rejected.
All valid periods are half-open.
## Registry collaborators
`DefaultRegistry` is the only source of the seven report definitions.
`DefaultRegistry` is the only source of the four report definitions.
`Lookup`, `Resolve`, and report-name helpers prevent callers from duplicating
report identity rules. Registry overrides clone a definition and replace its
module list only after the report ID is recognized.
@@ -54,13 +48,12 @@ membership and produces the actual batch plan.
Each definition supplies an ordered `[]module.ConfigItem`; the complete
report-to-module mapping is maintained in [module internals](module.md).
`ArtifactGroup`, `BatchOutputName`, `Generated`, and comparison compatibility
`ArtifactGroup`, `BatchOutputName`, and comparison compatibility
are likewise consumed by state and orchestration rather than recomputed there.
Unknown report IDs or batch names, an invalid weekend resolution, and invalid
storm windows return errors. The registry never collects weather data, builds
modules, parses CLI flags, writes state, executes Scriptorium, or delivers a
report.
Unknown report IDs or batch names return errors. The registry never collects
weather data, builds modules, parses CLI flags, writes state, executes
Scriptorium, or delivers a report.
## Verification and invariants

View File

@@ -40,7 +40,7 @@ single-report artifact identifiers.
## Metadata and durable writes
`Metadata` is the durable inventory for a run. It records its schema version,
run identity, generated and valid timestamps, artifact group and mode, source
run identity, generated and valid timestamps, artifact group, source
content and provenance, and the module snapshot, data-package, preflight,
report, generated-artifact, and notification locations when present.
@@ -64,7 +64,6 @@ only considers an earlier compatible report in the same artifact group and
supports the comparison strategies defined by the report request:
- `same_valid_date` finds an earlier generated report for the same valid day.
- `weekend_window` finds a prior comparable weekend window.
The newest eligible metadata record wins; the current run is excluded.
Unreadable or malformed candidate metadata is ignored so a damaged historical