weatherreporter/docs/internal/state.md

State Internals

This document describes filesystem state in internal/state.

Purpose

internal/state owns managed workspace paths, atomic JSON writes, persisted metadata, prior snapshot lookup, and read-only artifact inspection helpers.

Inputs And Outputs

Inputs:

• workspace configuration
• resolved report definition and valid period
• module snapshot
• prompt input data package
• preflight artifact
• generated-text raw, run-result, validated text, and render-context artifacts
• rendered report path preparation request
• RunID for inspection lookups

Outputs:

• module snapshot JSON path
• prompt input data package YAML path
• render preflight JSON path
• generated-text raw JSON path
• generated-text run-result JSON path
• validated generated-text JSON path
• render context JSON path
• managed Markdown report path
• metadata JSON path
• prior comparable snapshot metadata
• loaded module snapshot, data package, generated text, generated-text run result, or render context
• recent report records for inspection

Boundaries

internal/state owns local filesystem layout, path validation, durable writes, metadata reads, prior lookup, and report listing. It does not fetch weather data, derive forecasts, build prompt input content, compare module contents, invoke Scriptorium, import adapter result types, or parse CLI flags.

Preflight persistence uses the state-owned PreflightArtifact shape. The app converts adapter render results into that shape before saving.

Config Fields Used

• workspace.root
• workspace.snapshots_dir
• workspace.reports_dir
• workspace.data_packages_dir
• workspace.preflight_dir
• workspace.notifications_dir

Workspace subdirectories must be relative paths that stay under workspace.root.

Managed Layout

Paths are derived from the resolved report definition's artifact group, the valid-period start date for dated artifacts, and the RunID.

<workspace.root>/
  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.modules.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.metadata.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.generated_text.raw.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.generated_text.run.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.generated_text.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.render_context.json
  data-packages/<artifact_group>/<YYYY-MM-DD>/<run_id>.data_package.yaml
  preflight/<artifact_group>/<YYYY-MM-DD>/<run_id>.render.json
  notifications/<artifact_group>/<YYYY-MM-DD>/<run_id>.distributor.json
  reports/<artifact_group>/<run_id>.md

Metadata is stored beside module snapshots and links the module snapshot, data package, preflight, report paths, notification path when attempted, and configured prompt location. For generated-text-template reports, metadata also records the generated text schema ID and links the raw generated text, Scriptorium run result, validated generated text, and render context artifacts. Markdown-report metadata omits those generated-text fields. Report listing walks metadata files under the snapshots directory.

Prior Lookup

Prior snapshot lookup reads stored metadata through the shared lookup path and selects the latest earlier snapshot whose report ID is compatible with the current report definition.

• Daily Report compares with prior Daily Report snapshots for the same valid local date.
• Today Report compares with prior Today Report snapshots for the same valid local date.
• Tomorrow Report compares with prior Tomorrow Report snapshots for the same valid local date.
• 3-Day Outlook compares with prior 3-Day snapshots for the same valid local date.
• Weekend Outlook compares with prior Weekend snapshots for the same weekend window.
• Hourly Report uses the rolling-window comparison strategy and currently returns no prior snapshot from filesystem lookup.
• Storm Report has no prior lookup because explicit event-window comparison is not searched by the filesystem store.

Writes And Inspection

Durable JSON writes use shared atomic file helpers. Generated-text raw and validated JSON artifacts are written atomically as bytes; generated-text run result and render context artifacts are written atomically as JSON. Managed Markdown reports are prepared by creating their parent directory; Scriptorium writes the report body to the prepared path. Extra Markdown copies are handled by app orchestration. Distributor notification debug artifacts are written atomically when notification is attempted and include rendered distributor pipeline ID, bundle ID, idempotency key, bundle paths, upload status, latest run status, and redacted errors.

Inspection helpers read existing metadata, module snapshot, data package, generated text, generated-text run result, and render context files. Missing metadata directories return no inspection records or no prior snapshot rather than creating state.

Failure Behavior

• Invalid workspace paths return validation errors.
• Missing required metadata fields prevent metadata writes.
• JSON writes use a temporary file followed by rename where practical.
• Read and decode failures include path context.
• Unknown RunIDs produce an actionable lookup error.

Tests

Inspect:

• internal/state/filesystem_test.go
• internal/app/app_test.go

Invariants

• Managed paths stay under the configured workspace root.
• Artifact grouping comes from report definitions.
• Metadata links artifacts produced for a run.
• Generated-text artifacts live under the snapshots tree beside module snapshots and metadata.
• Prior lookup is based on structured metadata, not rendered report text.