# Generated Text Internals

This document describes structured generated-text handling in
`internal/generatedtext`.

## Purpose

`internal/generatedtext` validates structured text returned for
generated-text-template reports and builds curated render contexts for
templates. The first implemented contract is the Hourly Report.

## Inputs And Outputs

Inputs:

- raw Hourly Report GeneratedText JSON
- report metadata from `internal/briefing`
- a module snapshot from `internal/module`
- validated hourly generated text

Outputs:

- typed `Hourly` generated text
- normalized stable JSON for validated hourly generated text
- typed `HourlyRenderContext` values for `internal/reporttemplate`

The hourly generated text JSON accepts:

```json
{
  "summary": "string",
  "timing": "string",
  "impacts": "string",
  "confidence": "string"
}
```

`summary`, `timing`, and `impacts` are required after trimming whitespace.
`confidence` is optional and omitted from normalized JSON when blank.

## Boundaries

- This package owns typed generated-text validation and render-context shaping.
- It uses typed module snapshot decoding through `module.StanzaValue`.
- It does not invoke Scriptorium, write state artifacts, choose report
  definitions, compare snapshots, or render templates directly in production
  workflows.
- It does not use a Go JSON Schema dependency; schema enforcement in Go is
  limited to typed JSON decoding, unknown-field rejection, and required-field
  checks.

## Failure Behavior

- Malformed generated-text JSON fails with decode context.
- Unknown generated-text JSON fields fail during decoding.
- Empty required hourly fields fail after trimming whitespace.
- Missing required render-context stanzas fail with the stanza name.
- Invalid render metadata, including missing timezone, missing generated time,
  or invalid valid period, fails before template rendering.

## Tests

Inspect:

- `internal/generatedtext/hourly_test.go`
- `internal/generatedtext/render_context_test.go`

## Invariants

- Render contexts are curated structs, not raw prompt-input packages.
- Required generated text is normalized before downstream artifact storage.
- Missing optional weather narrative stanzas produce empty or fallback render
  context fields rather than forcing raw module data into templates.