weatherreporter/docs/internal/state.md

State Internals

This document describes the implemented filesystem state boundary.

Purpose

internal/state owns durable artifact paths, atomic JSON writes, metadata, and prior Daily snapshot lookup.

Inputs and Outputs

Inputs:

• workspace configuration
• resolved report definition and valid period
• briefing package
• prompt input data package
• scriptorium render result
• rendered report path preparation

Outputs:

• briefing snapshot JSON
• prompt input data package JSON
• render preflight JSON
• Markdown report path
• metadata JSON
• prior Daily snapshot metadata when available

Boundaries

• This package owns managed workspace layout and narrow path validation.
• It does not fetch weather data, derive forecasts, build prompt inputs, invoke scriptorium, or compare briefing contents.

Config Fields Used

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

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

State Behavior

Managed artifact names use RunID, which is generated from report generation time and report ID. Daily metadata is stored beside Daily briefing snapshots by valid local date. Prior Daily snapshot lookup reads metadata for the same valid local date and returns the latest earlier run. The store prepares the managed Markdown report path before scriptorium run writes it.

Failure Behavior

Writes are atomic where practical: JSON is written to a temporary file in the target directory and then renamed into place. Invalid workspace paths and missing required metadata fields produce actionable errors.

Tests

Inspect:

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

Invariants

• Managed paths stay under the configured workspace root.
• Metadata links the artifacts produced for a run.
• Prior lookup is based on structured metadata, not rendered report text.